CommunityImagegithub.com

steipete/vm-lab

Laboratoire macOS VM avec Parallels : automatisation GUI, Peekaboo, TCC, Ghostty.

Qu'est-ce que vm-lab ?

Ce skill fournit une méthodologie complète et les commandes nécessaires pour utiliser une machine virtuelle macOS (Parallels) comme environnement de test isolé pour l'automatisation d'interface graphique (GUI). Il est conçu pour les développeurs travaillant sur des outils comme Peekaboo, qui nécessitent de capturer des captures d'écran, de simuler des clics et des frappes, ou de tester les invites de permissions TCC (Transparency, Consent, and Control) sans risquer de corrompre l'état de l'hôte. L'approche clé est la *validation bidirectionnelle* : exécuter l'outil à l'intérieur de la VM invitée et vérifier son comportement depuis l'extérieur via des captures d'écran Parallels et des observations sur l'hôte, garantissant ainsi des tests fiables. Il couvre la découverte de VM, l'exécution de commandes via `prlctl exec`, et l'injection de touches via Ghostty pour une attribution correcte de l'enregistrement d'écran. Le skill met en garde contre les pièges connus comme l'échec du presse-papiers en mode headless ou les différences de codes de touches, et insiste sur l'utilisation de scripts courts et de lanceurs pour éviter les erreurs de frappe. Les plateformes supportées sont implicitement macOS en tant qu'hôte et invité, utilisant l'hyperviseur Parallels Desktop.

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

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

VM Lab

Utilisez ceci lorsque la tâche nécessite une VM macOS propre pour tester l'automatisation GUI, les invites TCC, la capture d'écran, les clics, la saisie, les performances ou la « validation bidirectionnelle » d'outils de type Peekaboo.

Idée centrale : exécutez l'outil testé à l'intérieur de l'invité, mais vérifiez-le depuis l'extérieur à l'aide de captures d'écran Parallels et d'observations sur l'hôte. Ne fermez pas les applications que vous ne possédez pas.

Règles de sécurité

  • Considérez l'instantané de la VM comme jetable, pas l'hôte.
  • Ne divulguez jamais de secrets. Si op est nécessaire, suivez le skill 1Password et exécutez-le uniquement à l'intérieur de tmux.
  • Préférez les nouvelles fenêtres d'application que vous créez vous-même : TextEdit, une page de test HTML locale ou une petite application test.
  • Évitez de modifier l'état de l'hôte à l'exception des captures d'écran temporaires sous /tmp.
  • Pour les dépôts git dans la VM, utilisez des remotes HTTPS et une discipline de branche normale.

Découverte de VM

Listez les VM :

prlctl list --all

Obtenez le statut/IP de la VM :

prlctl list --info "macOS Tahoe"

Exécutez des commandes dans l'invité en tant que Peter :

prlctl exec "macOS Tahoe" \
  'sudo -u steipete -H /bin/zsh -lc '\''source ~/.zprofile 2>/dev/null || true; uname -a'\'''

Capturez une capture d'écran indépendante du côté de l'hôte :

prlctl capture "macOS Tahoe" --file /tmp/vm-reference.png
sips -g pixelWidth -g pixelHeight /tmp/vm-reference.png

Attribution TCC/GUI

Pour l'enregistrement d'écran et l'accessibilité macOS, le processus responsable est important.

  • prlctl exec est sans tête (headless) et peut ne pas produire une attribution d'enregistrement d'écran correcte.
  • Lancez la commande test à partir d'une application de terminal visible dans l'invité lorsque l'enregistrement d'écran est impliqué.
  • Ghostty fonctionne comme terminal graphique s'il est installé.
  • Après un premier échec de capture, vérifiez Réglages Système > Confidentialité et sécurité > Enregistrement d'écran et audio système („System Settings > Privacy & Security > Screen & System Audio Recording“).
  • permissions status exécuté via prlctl exec peut encore indiquer un enregistrement d'écran faux après que Ghostty a été autorisé ; validez l'enregistrement d'écran en relançant la capture depuis Ghostty.

Ouvrez le panneau d'enregistrement d'écran :

prlctl exec "macOS Tahoe" \
  'sudo -u steipete -H open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"'

Ouvrez Ghostty :

prlctl exec "macOS Tahoe" 'sudo -u steipete -H open -a Ghostty'

Exécution de commandes via Ghostty

Meilleure approche : créez un script invité avec prlctl exec, ouvrez/focalisez Ghostty, puis tapez uniquement un chemin de lanceur court dans le terminal visible.

Modèle de script invité :

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 "Appuyez sur Retour pour fermer..."
read _
exit $rc
EOF
chmod +x /tmp/run-vm-lab.zsh
ln -sf /tmp/run-vm-lab.zsh /tmp/r
open -a Ghostty'\'''

Ensuite, créez un lien du lanceur dans le répertoire personnel de Ghostty et tapez ./r avec scripts/parallels_type.py. Cela évite les caractères de chemin peu fiables dans l'injection de touches 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'

Évitez de taper de longues commandes. L'injection de touches Parallels utilise son propre tableau de codes de touches et peut être sensible à la disposition du clavier.

Pièges connus

  • Les API du presse-papiers macOS peuvent échouer depuis prlctl exec ; pbcopy, le presse-papiers AppleScript et le collage Peekaboo peuvent tous échouer dans un contexte invité sans tête.
  • open -na Ghostty.app --args -e ... peut uniquement focaliser une fenêtre Ghostty existante sur macOS ; ne supposez pas qu'il exécute la commande.
  • prlctl exec peut réassembler les arguments via un shell invité ; pour des charges utiles complexes, passez une chaîne de commande entièrement échappée pour le shell ou créez le fichier avec un petit script Python.
  • send-key-event --key de Parallels utilise les valeurs de clé Parallels, pas les codes de touche virtuels macOS.
  • Pour la saisie normale, envoyez prlctl send-key-event <vm> --key <key> sans --event ; press/release explicite peut se répéter ou rester bloqué. Retour est une exception : utilisez d'abord press puis release.
  • Préférez un lot prlctl send-key-event --json plutôt que de nombreux processus send-key-event séparés ; des appels séparés peuvent dériver en raison de la latence/focalisation.
  • Utilisez 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 les frappes produisent des caractères indésirables, envoyez Retour pour effacer la ligne, créez un lanceur plus court, puis réessayez.
  • Si les sondes de permission Peekaboo se bloquent avec un enregistrement d'écran manquant et émettent SWIFT TASK CONTINUATION MISUSE, signalez-le comme un bogue de produit ; ne le confondez pas avec le harnais VM.

Validation bidirectionnelle

Pour chaque action GUI, vérifiez via deux signaux indépendants :

  • Sortie de l'outil testé : JSON, fichier de capture d'écran, résultat AX ou état de l'application.
  • Vérificateur externe : prlctl capture, inspection d'image côté hôte, contenu de fichier dans l'invité, ou état du processus/fenêtre.

Exemples :

  • Capture d'écran : comparez les dimensions/contenu de l'image Peekaboo avec prlctl capture.
  • Clic : utilisez Peekaboo pour cliquer sur un bouton de test, puis vérifiez à la fois l'état de l'application invitée et la capture d'écran de l'hôte.
  • Saisie : utilisez Peekaboo pour taper dans un champ de texte contrôlé, puis vérifiez la valeur AX et la capture d'écran de l'hôte.
  • Performance : encapsulez les commandes avec /usr/bin/time -p ; répétez les exécutions à froid/à chaud ; conservez les sorties dans /tmp.

Ligne de base Peekaboo VM

Dans l'invité :

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

Capture de référence côté hôte :

prlctl capture "macOS Tahoe" --file /tmp/vm-prlctl-reference.png

Capture Peekaboo côté invité via Ghostty :

/tmp/r

Comparez :

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

Rapport

Lors de la transmission, incluez uniquement :

  • Nom de la VM et version du système d'exploitation.
  • Commit du dépôt testé.
  • État des permissions.
  • Commandes ayant réussi/échoué.
  • Résultat du vérificateur indépendant.
  • Bogues de produit découverts.

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.

Skills associés