tui-inspector

name	tui-inspector
description	Records terminal UIs with VHS and deterministic snapshots. Use when debugging TUI rendering, reproducing visual regressions, or sharing keyboard-driven UI behavior.

TUI Inspector

Use this skill to create reproducible TUI video + screenshot artifacts with the tooling in /dp/tui_inspector.

Quick Start

bash /dp/tui_inspector/scripts/capture_mcp_agent_mail_tui.sh \
  --profile analytics-seeded \
  --binary /data/tmp/cargo-target/debug/mcp-agent-mail \
  --project-dir /data/projects/mcp_agent_mail_rust

Outputs:

• MP4 video at --output
• PNG snapshot at <output_basename>.png (unless --no-snapshot)

Workflow

• Confirm dependencies: vhs, ttyd, and optional ffmpeg
• Pick a profile (analytics-empty, analytics-seeded, messages-seeded, tour-seeded)
• Run capture with explicit --binary, --project-dir
• Inspect generated PNG first for quick verification
• Share MP4 plus run metadata for full playback context

Why This Is Reliable

• Forces MCP mode (unset AM_INTERFACE_MODE)
• Uses isolated runtime state: DATABASE_URL='sqlite:///.../storage.sqlite3' and per-run STORAGE_ROOT
• Optional live seeding via MCP HTTP JSON-RPC to avoid empty captures
• Avoids flaky captures from locked/shared local DB files

Commands

List profiles:

bash /dp/tui_inspector/scripts/capture_mcp_agent_mail_tui.sh --list-profiles

Empty-state baseline:

bash /dp/tui_inspector/scripts/capture_mcp_agent_mail_tui.sh \
  --profile analytics-empty \
  --binary /data/tmp/cargo-target/debug/mcp-agent-mail \
  --project-dir /data/projects/mcp_agent_mail_rust

Seeded analytics:

bash /dp/tui_inspector/scripts/capture_mcp_agent_mail_tui.sh \
  --profile analytics-seeded \
  --binary /data/tmp/cargo-target/debug/mcp-agent-mail \
  --project-dir /data/projects/mcp_agent_mail_rust

Seeded messages:

bash /dp/tui_inspector/scripts/capture_mcp_agent_mail_tui.sh \
  --profile messages-seeded \
  --binary /data/tmp/cargo-target/debug/mcp-agent-mail \
  --project-dir /data/projects/mcp_agent_mail_rust

Custom key script:

bash /dp/tui_inspector/scripts/capture_mcp_agent_mail_tui.sh \
  --profile analytics-empty \
  --keys "#,sleep:6,?,sleep:2,q"

Suite mode:

bash /dp/tui_inspector/scripts/run_mcp_agent_mail_tui_suite.sh \
  --profiles analytics-empty,analytics-seeded,messages-seeded \
  --suite-name nightly_smoke

Report generation from existing suite:

bash /dp/tui_inspector/scripts/generate_tui_inspector_report.sh \
  --suite-dir /tmp/tui_inspector/suites/nightly_smoke

Doctor checks:

bash /dp/tui_inspector/scripts/doctor_tui_inspector.sh

Common Flags

• --jump-key "#": switch to analytics screen (legacy alias mode)
• --boot-sleep 6: wait for TUI boot before keypress
• --capture-sleep 8: hold legacy jump target before quit
• --snapshot-second 9: timestamp to extract PNG frame
• --no-snapshot: skip PNG extraction
• --seed-demo: enable live JSON-RPC data seeding
• --seed-messages 12: increase data density
• --run-name my_case: stable artifact directory name
• --seed-required: fail run when seeding fails
• --snapshot-required: fail run when snapshot extraction fails

Operating Modes

Use these explicit modes to avoid accidental misuse:

1. Empty-state regression mode: --profile analytics-empty when validating layout/text/chrome behavior independent of data.
2. Seeded-state behavior mode: --profile analytics-seeded or messages-seeded when validating data visibility and event-driven changes.
3. End-to-end smoke mode: suite runner with --fail-fast and strict pass-through flags (--seed-required, --snapshot-required).
4. Forensic mode: preserve full run artifacts and inspect run_meta.json, vhs.log, and seeder logs before reruns.

Decision Matrix

Use this fast selection guide:

• Need to verify a static rendering bug quickly: use single run + analytics-empty.
• Need to prove data does not display: use analytics-seeded with --seed-required.
• Need confidence across multiple screens: use suite mode with tour-seeded.
• Need CI signal quality: use suite mode + strict flags + deterministic --suite-name.

Artifacts

Each run stores:

• capture.tape (exact tape used)
• vhs.log
• run_summary.txt
• run_meta.json
• capture.mp4
• snapshot.png (unless disabled)
• seed.log + stdout/stderr logs when seeding is enabled
• suite-level outputs: suite_summary.txt, suite_manifest.json, report.json, index.html

Default root:

/tmp/tui_inspector/runs/<timestamp>_<profile>/

Metadata Contract

run_meta.json should be treated as the canonical machine-readable outcome. Core fields to trust:

• status
• duration_seconds
• vhs_exit_code
• seed_exit_code
• snapshot_status
• video_exists
• snapshot_exists
• video_duration_seconds

In suite mode, use:

• suite_summary.txt for human quick scan
• suite_manifest.json for machine consumption
• report.json for report-backed pipelines

Validation

bash /dp/tui_inspector/scripts/capture_mcp_agent_mail_tui.sh --help
bash /dp/tui_inspector/scripts/capture_mcp_agent_mail_tui.sh --list-profiles
bash /dp/tui_inspector/scripts/run_mcp_agent_mail_tui_suite.sh --help
bash /dp/tui_inspector/scripts/generate_tui_inspector_report.sh --help
bash /dp/tui_inspector/scripts/doctor_tui_inspector.sh --help
validate-skill.py /cs/tui-inspector/ --verbose

CI and Automation Defaults

Recommended strict CI invocation:

bash /dp/tui_inspector/scripts/run_mcp_agent_mail_tui_suite.sh \
  --profiles analytics-empty,analytics-seeded,messages-seeded \
  --suite-name "ci_${GITHUB_RUN_ID:-manual}" \
  --fail-fast \
  -- --seed-required --snapshot-required

Recommended post-step bundle:

suite_dir="/tmp/tui_inspector/suites/ci_${GITHUB_RUN_ID:-manual}"
tar -czf "${suite_dir}.tar.gz" -C "$(dirname "$suite_dir")" "$(basename "$suite_dir")"

Anti-Patterns

• Running seeded profiles without --seed-required when outcome strictness matters.
• Comparing screenshots without retaining run_meta.json and vhs.log.
• Reusing ambiguous run names in CI.
• Treating a passing MP4 generation as success when seed_exit_code failed.
• Skipping doctor checks after dependency or environment changes.

Fast Incident Workflow

1. Run doctor: bash /dp/tui_inspector/scripts/doctor_tui_inspector.sh
2. Run single strict seeded capture: capture_mcp_agent_mail_tui.sh --profile analytics-seeded --seed-required --snapshot-required
3. If failure: inspect run_meta.json first, then vhs.log, then seed.stderr.log.
4. Run minimal suite for blast-radius check: analytics-empty,messages-seeded.
5. Generate report and attach bundle to issue/PR.

Preserved Baseline Content

The following baseline content is intentionally preserved (reorganized only):

• Quick-start capture command for analytics
• Output contract (--output, <output_basename>.png)
• Workflow checklist (deps, run, inspect PNG, share MP4)
• Reliability rationale (MCP mode + isolated runtime state)
• Common flags (--jump-key, --boot-sleep, --capture-sleep, --snapshot-second, --no-snapshot)
• Validation command pattern

References

• Operational playbook: PLAYBOOK.md
• Suite/report cookbook: SUITE_AND_REPORT.md
• Failure triage map: TROUBLESHOOTING.md
• Mode selection matrix: MODE_SELECTION.md
• CI contract: CI_CONTRACT.md
• Anti-pattern catalog: ANTI_PATTERNS.md
• Forensics handbook: FORENSICS.md
• Command catalog: COMMAND_CATALOG.md

Reference Index

• PLAYBOOK.md
• SUITE_AND_REPORT.md
• TROUBLESHOOTING.md
• MODE_SELECTION.md
• CI_CONTRACT.md
• ANTI_PATTERNS.md
• FORENSICS.md
• COMMAND_CATALOG.md