tuistory

Tuistory Driver

オーケストレーターによってここに案内されました。以下の仕組みを使って、計画を実行してください。

Playwright 形式の CLI を使い、仮想 PTY で対象コマンドを起動して、文字入力、キー押下、待機、スナップショットの取得、記録を行います。

使用する場面

• 日常的な TUI の自動化や回帰チェック
• 仮想画面バッファーを対象にした、決定的な wait／wait-idle
• ユーザーに表示される内容をそのまま反映したテキストスナップショット
• 実際の端末でのキーボードエンコーディングを証明する必要がないシナリオ

特定のキー入力に対して Ghostty や Kitty が実際に何を出力するかを証明する必要がある場合は、代わりに true-input を使用してください。

前提条件

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

任意：tmux（スクロールバックの操作）、asciinema（録画）、agg（.cast から .gif への変換）。

基本パターン

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

注： droid-dev の起動には --repo-root が必須です。tctl によって適用されます。

起動時には必ず --env FORCE_COLOR=3 --env COLORTERM=truecolor を渡してください。 仮想 PTY はカラーサポートを通知しないため、これらを指定しないと、Node.js アプリ（Ink／chalk）はすべてのカラーエスケープコードを抑制します。

コマンドリファレンス（tctl 経由）

コマンド	目的
launch <cmd> -s <name> --backend tuistory	tuistory セッションを開始します
type <text>	文字列をそのまま送信します
press <key> [keys...]	キーの組み合わせを送信します（例：press shift enter）
wait <pattern>	テキストまたは /regex/ が表示されるまで待機します
wait-idle	出力が安定するまで待機します
snapshot [--trim]	整形したテキストを出力します（--trim は末尾の空白を削除します）
close	セッションを終了します

起動オプション：--cols <n>、--rows <n>、--cwd <path>（子プロセスの作業ディレクトリ。--repo-root が設定されている場合はその値がデフォルトです）、--env KEY=VALUE、--record <path>。

録画

起動時に --record を渡してください。tctl は PTY の周りで asciinema rec をラップするため、録画は必ず起動時に設定する必要があります（素の tuistory では録画できません）。

$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
# ... interact ...
$TCTL -s demo close    # finalizes the .cast

実行前後の比較 — 異なるワークツリーに対して 2 つのセッションを起動します。

$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

再生：asciinema play /tmp/demo.cast

tmux（スクロールバックの操作のみ）

デモで端末エミュレーターのスクロールバックが必要で、アプリが標準バッファー（代替画面ではない）を使う場合にのみ必要です。true-input セッションでは、通常 tmux は不要です。実際の端末がネイティブのスクロールバックを管理するためです。

起動時に --tmux を使用してください。tctl はコマンドを tmux 内で実行し、TERM=xterm-256color で tmux を起動します。また、default-terminal=tmux-256color、terminal-features=...,xterm-256color:RGB、terminal-overrides=...,xterm-256color:Tc（tmux 3.2 未満の場合のフォールバック）、COLORTERM=truecolor（set-environment 経由）、escape-time=50、mode-keys=vi を事前設定します。

コピーモード：ctrl-b [ で開始し、g g で先頭へ、shift-g で末尾へ、ctrl-u／ctrl-d で半ページ移動、/ で検索し、q で終了します（esc ではありません）。

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

録画に tmux の再描画が含まれる場合、asciinema は tmux の内側ではなく外側をラップする必要があります。

既知の行き止まり

• 素の asciinema rec：asciinema rec を直接呼び出さないでください。tctl --record は PTY の周りで asciinema rec をラップするため、tuistory-relay が引き続きセッションを管理し、インタラクティブな TUI（Ink／React）が正しく stdin を受け取ります。asciinema rec を手動で呼び出すと、この接続が迂回されます。その結果、stdin の転送が壊れ、入力したキーが子プロセスではなく外側の PTY に表示され、tuistory コマンド（wait、snapshot、close）からセッションを見つけられなくなります。
• tctl のフラグを指定した素の tuistory launch：tuistory は --record、--backend、--repo-root、--env フラグに対応していません。これらを渡すと tuistory-relay がクラッシュします。起動にはすべて tctl を使用してください。

復旧

$TCTL -s demo press esc         # bail out of a stuck dialog
$TCTL -s demo snapshot --trim   # check visible state
$TCTL -s demo close             # hard reset

代替手段：素の tuistory（最終手段）

tctl 自体が壊れているか利用できない場合に限り、録画しないセッションであれば素の tuistory を代わりに使用できます。素の tuistory が受け付けるのは --cols、--rows、-s のみで、ほかのフラグには対応していません。--record、--backend、--repo-root、--env、--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