Pilote Tuistory

L'orchestrateur t'a dirigé ici. Utilise ces mécanismes pour exécuter ton plan.

Lance une commande cible dans un PTY virtuel avec une CLI de style Playwright pour taper du texte, appuyer sur des touches, attendre, prendre des snapshots et enregistrer.

Quand l'utiliser

• Automatisation TUI courante et vérifications de régression
• wait / wait-idle déterministe sur le tampon d'écran virtuel
• Snapshots texte de exactement ce que l'utilisateur verrait
• Tout scénario où tu n'as pas besoin de prouver l'encodage réel du clavier du terminal

Si tu dois prouver ce que Ghostty ou Kitty émet vraiment pour une touche donnée, utilise true-input à la place.

Prérequis

npm install -g tuistory    # ou : bun add -g tuistory

Optionnel : tmux (flux de scrollback), asciinema (enregistrements), agg (.cast vers .gif).

Motif cœur

TCTL=${DROID_PLUGIN_ROOT}/bin/tctl

$TCTL launch "droid-dev" -s demo --backend tuistory \
  --repo-root /path/to/worktree \
  --cols 120 --rows 36 \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor
$TCTL -s demo wait ">" --timeout 15000
$TCTL -s demo type "hello"
$TCTL -s demo press enter
$TCTL -s demo snapshot --trim
$TCTL -s demo close

Note : --repo-root est obligatoire pour les lancements droid-dev — tctl l'impose.

Passe toujours --env FORCE_COLOR=3 --env COLORTERM=truecolor au lancement. Le PTY virtuel n'annonce pas le support des couleurs, donc les apps Node.js (Ink/chalk) suppriment tous les codes d'échappement de couleur sans ces variables.

Référence de commandes (via tctl)

Options de lancement : --cols <n>, --rows <n>, --cwd <path>, --env KEY=VALUE, --record <path>.

Enregistrement

Passe --record au lancement. tctl enveloppe asciinema rec autour du PTY, donc l'enregistrement doit être défini au moment du lancement (le tuistory brut ne peut pas enregistrer) :

$TCTL launch "droid-dev" -s demo --backend tuistory \
  --repo-root /path/to/worktree \
  --cols 120 --rows 36 --record /tmp/demo.cast \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor
# ... interagir ...
$TCTL -s demo close    # finalise le .cast

Comparaison avant/après — lance deux sessions contre différents worktrees :

$TCTL launch "droid-dev" -s before --backend tuistory \
  --repo-root /path/to/baseline-worktree \
  --cols 120 --rows 36 --record /tmp/before.cast \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor

$TCTL launch "droid-dev" -s after --backend tuistory \
  --repo-root /path/to/candidate-worktree \
  --cols 120 --rows 36 --record /tmp/after.cast \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor

Lecture : asciinema play /tmp/demo.cast

tmux (flux de scrollback uniquement)

Nécessaire seulement quand la démo requiert un scrollback de l'émulateur de terminal et que l'app utilise le tampon standard (pas l'écran alternatif). Les sessions true-input ont rarement besoin de tmux car le terminal réel possède un scrollback natif.

Utilise --tmux au lancement. tctl enveloppe la commande dans tmux, démarre tmux avec TERM=xterm-256color, et préconfigure default-terminal=tmux-256color, terminal-features=...,xterm-256color:RGB, terminal-overrides=...,xterm-256color:Tc (fallback pour tmux < 3.2), COLORTERM=truecolor (via set-environment), escape-time=50, et mode-keys=vi.

Mode copie : ctrl-b [ pour entrer, g g en haut, shift-g en bas, ctrl-u/ctrl-d demi-page, / recherche, q pour quitter (pas esc).

Lancer avec tmux :

$TCTL launch "droid-dev" -s demo --backend tuistory --tmux \
  --repo-root /path/to/worktree \
  --cols 120 --rows 36 --record /tmp/demo.cast \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor

Quand l'enregistrement inclut les redessin de tmux, asciinema doit envelopper tmux, pas l'inverse.

Impasses connues

• asciinema rec brut : N'appelle pas asciinema rec directement. tctl --record enveloppe asciinema rec autour du PTY pour que tuistory-relay conserve la session et que les TUI interactives (Ink/React) reçoivent stdin correctement. Appeler asciinema rec manuellement contourne ce câblage — le transfert stdin se casse, les touches tapées s'affichent sur le PTY externe au lieu d'atteindre l'enfant, et les commandes tuistory (wait, snapshot, close) ne trouvent pas la session.
• tuistory launch brut avec les flags tctl : tuistory n'a pas de flags --record, --backend, --repo-root, ou --env. Les passer crash tuistory-relay. Utilise tctl pour tous les lancements.

Récupération

$TCTL -s demo press esc         # s'échapper d'une boîte de dialogue bloquée
$TCTL -s demo snapshot --trim   # vérifier l'état visible
$TCTL -s demo close             # réinitialisation forcée

Trappe de secours : tuistory brut (dernier recours)

Si tctl lui-même est cassé ou indisponible, tu peux revenir à tuistory brut pour les sessions sans enregistrement uniquement. Le tuistory brut accepte seulement --cols, --rows, et -s — aucun autre flag. Ne passe pas --record, --backend, --repo-root, --env, ou --tmux.

tuistory launch "my-tui-app" -s demo --cols 120 --rows 36
tuistory -s demo wait ">" --timeout 15000
tuistory -s demo snapshot --trim
tuistory -s demo close