dbtool-cli-v1/TUI_SMOKE_RUNBOOK.md

dbtool-tui TTY Smoke Runbook

Contract

• dbtool-tui 是交互式 TUI；启动验证必须提供真实 TTY。
• 当前最小可重复入口是 scripts/tui/smoke-tty.sh <binary-path>。
• dbtool-tui --help、dbtool-tui --version 不是有效的 TUI smoke 替代路径。
• 非 TTY 启动当前应退出 1，并输出明确的 TTY-required 提示。

前置条件

• Linux runner，且可用 script（util-linux）。
• 已有可执行二进制：
  • 源码环境：CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse cargo build -p dbtool-tui
  • release binary 复验：CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse cargo build --release -p dbtool-tui
  • 无 Rust 工具链环境：直接使用 ./target/debug/dbtool-tui
• 若当前 runner 的 CARGO_REGISTRIES_CRATES_IO_PROTOCOL 为空字符串，裸 cargo 会直接失败；请按上面的显式 override 执行。

最小入口

正常终端尺寸：

scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui
grep -aq "Workspace" /tmp/dbtool-tui-smoke.log
grep -aq "Loading" /tmp/dbtool-tui-smoke.log

release binary 同口径：

scripts/tui/smoke-tty.sh ./target/release/dbtool-tui 40 120 /tmp/cmp60-dbtool-tui-release-smoke.log
grep -aq "Workspace" /tmp/cmp60-dbtool-tui-release-smoke.log
grep -aq "Loading" /tmp/cmp60-dbtool-tui-release-smoke.log

小终端降级：

scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui 20 90 /tmp/dbtool-tui-small.log
grep -aq "Terminal Too Small" /tmp/dbtool-tui-small.log
grep -aq "Resize the terminal" /tmp/dbtool-tui-small.log

PostgreSQL / MySQL live path

• 当前 runner 的可达 network path 是 host.docker.internal:55432（PostgreSQL）与 host.docker.internal:53306（MySQL），不是 127.0.0.1。
• 当前 runner 即使缺少 docker compose 子命令，也可通过 scripts/tui/demo-stack.sh 与 bootstrap fallback 建立同一套 demo 数据。
• 当前推荐的单命令复验入口：

export DBTOOL_PASSWORD=dbtool
scripts/tui/live-network-smoke.sh postgres ./target/debug/dbtool-tui
scripts/tui/live-network-smoke.sh mysql ./target/debug/dbtool-tui

• 这两条命令只验证内置 demo profile 的 activate / inspect / query / export，不覆盖连接新增 / 编辑 / 删除 / 保存或 secret session cache。

• 若 GUI host 或宿主机必须把 demo host 改到 127.0.0.1，请在启动前设置 DBTOOL_TUI_POSTGRES_HOST / DBTOOL_TUI_POSTGRES_PORT 与 DBTOOL_TUI_MYSQL_HOST / DBTOOL_TUI_MYSQL_PORT；这是 operator fallback，不得记成连接管理 happy path。

• 若只想准备 demo stack 与 seed 数据：

scripts/tui/demo-stack.sh up
scripts/tui/demo-stack.sh seed
scripts/tui/demo-stack.sh status

Connection management smoke

若要复核新的 in-app 连接管理路径，建议先隔离 profile store：

export DBTOOL_TUI_PROFILE_STORE=/tmp/dbtool-tui-profiles.json
rm -f "$DBTOOL_TUI_PROFILE_STORE"
cargo run -p dbtool-tui

进入 TUI 后按下面的手工路径复核：

1. 按 2 进入 Connections
2. 按 n 新建 profile
3. 在中间 Query Editor 中用 i 编辑字段，Enter 提交字段
4. 按 t 做 staged connect + inspect 测试
5. 按 s 保存并激活 profile
6. 确认左侧列表、右侧 Inspector 和 Status & Activity 同步切到新活动连接
7. 按 e 编辑已保存 profile，确认修改可再次测试并保存
8. 按 d 删除 profile，确认 Enter 才执行删除，Esc 可取消

记录时至少包含：

• DBTOOL_TUI_PROFILE_STORE 的实际路径
• 新建 profile 的 driver 类型（SQLite / PostgreSQL / MySQL）
• t 的结果文案
• s 后的激活结果与当前连接名称
• 删除确认路径是否被 Enter / Esc 正确区分

非 TTY 预期行为

./target/release/dbtool-tui --help

2026-03-31 当前 release binary 实测行为：

• 退出码：1
• stderr：
  • dbtool-tui requires an interactive TTY on stdin and stdout.
  • Detected stdin TTY: false
  • Detected stdout TTY: false
  • Use \scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui` for repeatable smoke validation.`
  • `--help` is not a supported TUI smoke path.

这条路径的意义是确认“限制被清楚记录”，不是把 --help 视为 smoke 成功。

QA 记录要求

• 记录二进制路径、命令、终端尺寸、退出码、日志路径。
• 正常尺寸至少确认日志里出现 Workspace、Loading。
• 小终端路径至少确认日志里出现 Terminal Too Small、Resize the terminal。
• network live 路径至少记录目标数据库、endpoint、导出路径和日志路径。
• 若使用 host override，额外记录具体环境变量；不得把这条路径写成普通用户主流程。
• 若源码不可重建，要明确记为环境 blocker，不得伪造成产品失败。

CI 约束

• 当前仓库还没有正式接入 dbtool-tui 的 GitHub Actions smoke。
• 当前仓库也还没有 dbtool-tui 的 packaged-artifact workflow / package script；target/release/dbtool-tui 只能记为 release-binary 级别证据，不能上抬成已验证的 distributable artifact。
• 后续 CI 若补齐，应直接复用 scripts/tui/smoke-tty.sh，不要重新发明另一套启动口径。