feat(usable): package gui-host validation snapshot

Co-Authored-By: Paperclip <noreply@paperclip.ing>

TUI_SMOKE_RUNBOOK.md

@@ -0,0 +1,85 @@
+# 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`
+  - 无 Rust 工具链环境：直接使用 `./target/debug/dbtool-tui`
+- 若当前 runner 的 `CARGO_REGISTRIES_CRATES_IO_PROTOCOL` 为空字符串，裸 `cargo` 会直接失败；请按上面的显式 override 执行。
+
+## 最小入口
+
+正常终端尺寸：
+
+```bash
+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
+```
+
+小终端降级：
+
+```bash
+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 数据。
+- 当前推荐的单命令复验入口：
+
+```bash
+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 stack 与 seed 数据：
+
+```bash
+scripts/tui/demo-stack.sh up
+scripts/tui/demo-stack.sh seed
+scripts/tui/demo-stack.sh status
+```
+
+## 非 TTY 预期行为
+
+```bash
+./target/debug/dbtool-tui --help
+```
+
+2026-03-28 当前源码重建后二进制实测行为：
+
+- 退出码：`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、导出路径和日志路径。
+- 若源码不可重建，要明确记为环境 blocker，不得伪造成产品失败。
+
+## CI 约束
+
+- 当前仓库还没有正式接入 `dbtool-tui` 的 GitHub Actions smoke。
+- 后续 CI 若补齐，应直接复用 `scripts/tui/smoke-tty.sh`，不要重新发明另一套启动口径。