Utilisation du terminal

L'orchestrateur t'a routé ici pour toute cible terminal. Sélectionne le backend, puis exécute ton plan via tctl.

Sélectionner le backend

Besoin	Backend	Mécaniques
Automatisation TUI courante, vérifications de régression, `wait` / `wait-idle` déterministes, snapshots texte de ce que l'utilisateur verrait, enregistrements de démonstration	`tuistory` (défaut)	Ce fichier
Rendu de terminal réel, ou preuve de ce que Ghostty ou Kitty émettent vraiment pour une frappe	`true-input`	Charge true-input ; il possède le compositeur, la VM et les mécaniques de plateforme

Utilise tuistory sauf si la réclamation porte sur le terminal réel lui-même. Le reste de ce fichier concerne le backend tuistory : une commande cible dans un PTY virtuel avec CLI de style Playwright pour taper, appuyer sur des touches, attendre, faire des snapshots et enregistrer.

Prérequis

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

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

Schéma principal

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.

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

Référence des commandes (via tctl)

Commande	But
`launch <cmd> -s <name> --backend tuistory`	Démarrer une session tuistory
`type <text>`	Envoyer du texte littéral
`press <key> [keys...]`	Envoyer une combinaison de touches (ex. `press shift enter`)
`wait <pattern>`	Bloquer jusqu'à l'apparition de texte ou `/regex/`
`wait-idle`	Bloquer jusqu'à la stabilisation de la sortie
`snapshot [--trim]`	Imprimer le texte nettoyé (`--trim` supprime les blancs en fin de ligne)
`close`	Arrêter la session

Options de lancement : --cols <n>, --rows <n>, --cwd <path> (répertoire de travail de l'enfant ; défaut à --repo-root s'il est défini), --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 sur 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 seulement)

Nécessaire seulement quand la démonstration demande un scrollback d'émulateur de terminal et que l'app utilise le buffer standard (pas l'écran alternatif). Les sessions true-input ont rarement besoin de tmux car le terminal réel possède le 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 (secours pour tmux < 3.2), COLORTERM=truecolor (via set-environment), escape-time=50, et mode-keys=vi.

Copy-mode : ctrl-b [ pour entrer, g g haut, shift-g 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 des redessins tmux, asciinema doit envelopper tmux, pas l'inverse.

Impasses connues

Raw asciinema rec : N'appelle pas asciinema rec directement. tctl --record enveloppe asciinema rec autour du PTY pour que tuistory-relay possède toujours la session et que les TUI interactifs (Ink/React) reçoivent correctement stdin. Appeler asciinema rec manuellement contourne ce câblage — le forwarding de stdin 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.
Raw tuistory launch avec les flags tctl : tuistory n'a pas de flags --record, --backend, --repo-root, ou --env. Les passer casse tuistory-relay. Utilise tctl pour tous les lancements.

Récupération

$TCTL -s demo press esc         # bail out d'une dialog bloquée
$TCTL -s demo snapshot --trim   # vérifier l'état visible
$TCTL -s demo close             # reset forcé

Échappatoire : tuistory brut (dernier recours)

Si tctl lui-même est cassé ou indisponible, tu peux revenir à tuistory brut pour les sessions sans enregistrement seulement. Le tuistory brut n'accepte que --cols, --rows, et -s — pas d'autres flags. 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

terminal-use