Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 70 additions & 65 deletions .claude/skills/yourssh-screenshots/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,57 +5,83 @@ description: Use when the user wants to update, refresh, or add screenshots for

# yourssh-screenshots

Captures screenshots of every YourSSH feature screen using Flutter integration tests (render tree — no macOS Screen Recording permission needed). Saves PNGs to `screenshots/<group>/`, then updates README.
Default path: the **isolated docs journey** (`tool/docs_journey.sh`). It drives the real macOS app through every feature against demo Docker containers and captures ~209 PNGs (render tree, so no Screen Recording permission). The app runs with a temp `HOME`, in-memory prefs, fake secure storage and temp path_provider dirs, so the owner's real data is never touched; the script checks the real prefs plist mtime and `~/.yourssh` hash before/after (`ISOLATION OK`).

## Quick Reference
## Default workflow

```bash
# Capture all general feature screenshots
cd app && flutter test integration_test/feature_screenshots_test.dart -d macos

# Capture RDP-specific screenshots (requires Docker)
cd app && flutter test integration_test/rdp_screenshots_test.dart -d macos

# Capture Android/mobile screenshots (requires an emulator + Docker sshd)
flutter emulators --launch Medium_Phone_API_36.1
docker run -d --name yourssh-ssh-demo -p 2222:2222 \
-e PASSWORD_ACCESS=true -e USER_NAME=demo -e USER_PASSWORD=demo1234 \
lscr.io/linuxserver/openssh-server:latest
cd app && flutter drive \
--driver=test_driver/integration_test.dart \
--target=integration_test/mobile_screenshots_test.dart -d emulator-5554
tool/docs_journey.sh setup # client key + image + network + 5 demo containers (idempotent)
tool/docs_journey.sh all # build the integration app, then run desktop + mobile launches (~30 min, needs a GUI session)
# review screenshots/docs/INDEX.md (one line per shot) and screenshots/docs/BUGS.md (anomalies found)
tool/docs_journey.sh teardown # remove ONLY the containers/network/image that setup created
```

## Folder Structure
- Output: `screenshots/docs/<NN-section>/<NN-step>.png` + `INDEX.md` + `BUGS.md` (untracked; `DOCS_OUT` overrides).
- Subcommands: `setup | build | run | all | teardown`. `run` skips the build; `build` only builds.
- Re-run a subset: `SECTIONS="07,08" MODES=desktop tool/docs_journey.sh run` (section numbers are the `NN-` prefixes of `app/integration_test/docs/sNN_*.dart`; `MODES` is `desktop`, `mobile`, or both). Use `run` after one full `build`; rebuild (`build`) after any Dart change.
- Demo servers (loopback only; the harness expects these defaults): `yourssh-docs-ssh` 2222 (hostname `yourssh-demo`, user `demo`/`demo1234` + key auth), `yourssh-docs-bastion` 2223, `yourssh-docs-db` (network only, `db-internal:22`), `yourssh-docs-rdp` 3389 (`demo`/`demo12345`), `yourssh-docs-vnc` 5900 (`demo12345`). Image files: `tool/docs_journey/Dockerfile`.
- The generated ed25519 client key lives in `~/.local/state/yourssh-docs-journey` (`DOCS_KEY_DIR` overrides), never in the repo. Never commit keys.
- `DOCS_PREFIX` and `SSH_PORT/BASTION_PORT/RDP_PORT/VNC_PORT` let `setup`/`teardown` run side by side with another set of containers (only for testing setup; the journey itself needs the default ports).
- Timestamps/progress go to `$TMPDIR/yourssh-docs-run.*/run-*.log`; a hung mobile launch is retried once automatically.

## Refreshing the README images from a run

README images are copies of journey shots, resized: `sips -Z 1440 <src> --out <README path>` (writes a copy; never edit the source). Mapping (README path <- journey shot; confirm each against `screenshots/docs/INDEX.md` because shot numbers shift when sections change):

| README path (under `screenshots/`) | Journey shot |
|---|---|
| `01-terminal-ssh/01-hosts-dashboard.png` | `06-dashboard/01-grid.png` |
| `01-terminal-ssh/02-new-host-panel-ssh.png` | `02-add-host/01-new-host-panel.png` |
| `02-ssh-terminal-ai.png` | `16-ai-chat/04-chat-open.png` |
| `01-terminal-ssh/04-dashboard-with-rdp-badge.png` | `12-rdp/04-dashboard-rdp-badge.png` |
| `02-sftp/01-sftp-browser.png` | `07-sftp/03-dual-panel.png` |
| `03-port-forwarding/01-port-forward-rules.png` | `08-port-forwarding/05-rule-list.png` |
| `04-credentials-security/01-keychain.png` | `04-keychain/05-key-list.png` |
| `04-credentials-security/02-known-hosts.png` | `09-known-hosts/01-list.png` |
| `05-settings/01-settings-general.png` | `14-settings/01-settings-top.png` |
| `05-settings/02-settings-terminal.png` | `14-settings/03-terminal.png` |
| `05-settings/03-settings-sync.png` | `14-settings/09-sync.png` |
| `10-settings-sync-qr-code.png` | `14-settings/17-sync-qr-dialog.png` (see gaps) |
| `05-settings/04-settings-updates.png` | `14-settings/12-updates.png` |
| `05-settings/05-terminal-theme-picker.png` | `03-first-connect/19-theme-picker.png` |
| `06-plugins/01-plugins.png` | `15-plugins/01-manager.png` |
| `05-devops-hub-network-tools.png` | `17-devops/04-network-tools.png` |
| `08-web-tools-http-client.png` | `18-web-tools/03-get-response.png` |
| `09-snippets.png` | `15-plugins/03-snippets-screen.png` |
| `02-host-editor-rdp-form.png` | `12-rdp/03-editor-filled.png` |
| `03-tofu-certificate-dialog.png` | `12-rdp/05-cert-trust-dialog.png` |
| `04-rdp-workspace-connected.png` | `12-rdp/06-session-connected.png` |
| `05-fullscreen-with-pill.png` | `12-rdp/08-fullscreen-pill.png` |
| `06-fullscreen-clean.png` | `12-rdp/09-fullscreen-clean.png` |
| `07-fullscreen-hover-reveal.png` | `12-rdp/10-fullscreen-hover-pill.png` |
| `08-back-to-windowed.png` | `12-rdp/11-back-windowed.png` |
| `10-audit-recording/01-audit-log.png` | `11-audit-log/01-rows.png` |
| `10-audit-recording/02-recording-library.png` | `10-recordings/02-library.png` |
| `11-recording.png` | `10-recordings/03b-player-playing.png` |
| `12-multiple-player.png` | no journey shot (needs two clients; keep the existing image) |

After copying, check every README path exists:
```bash
grep -o 'screenshots/[^"]*\.png' README.md | while read p; do [ -f "$p" ] && echo "OK: $p" || echo "MISSING: $p"; done
```
screenshots/
01-terminal-ssh/ # Dashboard, host editor, SSH terminal
02-sftp/ # Dual-panel SFTP
03-port-forwarding/ # Port forward rules
04-credentials-security/ # Keychain, known hosts
05-settings/ # Settings sections
06-plugins/ # Plugin manager
07-rdp/ # RDP workspace (populated by rdp test)
08-devops/ # DevOps hub
10-audit-recording/ # Audit log, recording library
11-mobile/ # Android screens (populated by the mobile test)
*.png # Legacy flat screenshots (keep for features needing live connections)
```
New feature screens: add the step to the matching `app/integration_test/docs/sNN_*.dart`, rebuild, re-run that section, then add the README `<td>` (2-column `<table>` rows per feature group).

## Known gaps

## How It Works
- WebViews are blank in render-tree capture (embedded browser, Monaco code editor, web tools browser): only the surrounding chrome is real.
- Mobile pair / LAN-sync QR dialogs show the machine's real LAN IP. Before publishing, re-encode the QR with a placeholder address or crop it out; otherwise note it in the PR.
- Terminal sharing (multiplayer) and anything needing a second client are not covered.
- Real AI providers are never called (no key); RDP/VNC need the containers running and a window that stays awake (the script runs `caffeinate`).

`integration_test/feature_screenshots_test.dart`:
1. Backs up user's real host data
2. Seeds demo hosts + port forward rules into SharedPreferences
3. Launches `app.main()` via Flutter integration test harness
4. Navigates each sidebar section by tapping the nav label text
5. Captures frames via `RendererBinding.instance.renderViews.first`
6. Restores user data in `finally`
## Do not use the legacy path by default

`integration_test/rdp_screenshots_test.dart`:
- Requires `docker run -d --name yourssh-rdp-demo -p 3389:3389 scottyhardy/docker-remote-desktop:latest`
- Connects to a real xrdp container; captures fullscreen + TOFU dialog screenshots
`app/integration_test/feature_screenshots_test.dart` and `rdp_screenshots_test.dart` back up and seed the user's REAL SharedPreferences (hosts, known hosts, port forwards) and restore them afterwards. A crash mid-run can leave demo data in the real profile. Use them only if the user explicitly asks; the journey above replaces them.

```bash
# legacy, only on request
cd app && flutter test integration_test/feature_screenshots_test.dart -d macos
cd app && flutter test integration_test/rdp_screenshots_test.dart -d macos # needs the RDP container
```

## Mobile (Android) capture

Expand All @@ -79,7 +105,7 @@ Emulator gotchas: a full debug APK is ~185 MB, so `INSTALL_FAILED_INSUFFICIENT_S
means the AVD's `/data` is full — reboot the emulator to reclaim cache. Biometric
app-lock is force-disabled in setup because an emulator has no enrolled fingerprint.

## Adding a New Screen
## Adding a screen (legacy test only)

1. Open `app/integration_test/feature_screenshots_test.dart`
2. Navigate to the screen with `_navTo(tester, 'Label')` or tap the relevant widget
Expand All @@ -88,36 +114,15 @@ app-lock is force-disabled in setup because an emulator has no enrolled fingerpr
5. Run the test to verify
6. Add the `<img src="screenshots/NN-group-name/filename.png"/>` entry to README under the correct section

## Updating README

The `## Screenshots` section in `README.md` is organized by feature groups matching the folder structure. Each group uses an HTML `<table>` with 2-column rows:

```html
### Group Name
<table>
<tr>
<td align="center"><b>Screen Title</b><br/><img src="screenshots/NN-group/filename.png"/></td>
<td align="center"><b>Screen Title</b><br/><img src="screenshots/NN-group/filename.png"/></td>
</tr>
</table>
```

After updating, verify all paths exist:
```bash
grep -o 'screenshots/[^"]*\.png' README.md | while read p; do
[ -f "$p" ] && echo "OK: $p" || echo "MISSING: $p"
done
```

## Key Implementation Details
## Legacy test implementation details

- **Storage keys**: `yourssh.hosts`, `yourssh.known_hosts`, `yourssh.port_forwards` (not bare `hosts`)
- **Nav tap**: `find.text('Port Forwarding')`, `find.text('Known Hosts')`, etc. — matches sidebar label text
- **`_snap` helper**: pumps 200ms before capture to let animations settle
- **Debounce update check**: set `last_update_check` to `DateTime.now().millisecondsSinceEpoch` to prevent update banner polluting shots
- **PortForward JSON**: stored as a flat list, `type` is the enum name (`local`, `remote`, `dynamic`)

## Common Mistakes
## Common mistakes (legacy test)

| Problem | Fix |
|---|---|
Expand Down
70 changes: 66 additions & 4 deletions tool/docs_journey.sh
Original file line number Diff line number Diff line change
@@ -1,22 +1,84 @@
#!/usr/bin/env bash
# Builds and runs the docs screenshot journey with FULL isolation.
# tool/docs_journey.sh [build|run|all] (default: all)
# tool/docs_journey.sh [setup|build|run|all|teardown] (default: all)
# setup generate a client key, build the demo image, create the network and 5 demo containers (idempotent)
# build build the integration-test macOS app
# run launch the app against the demo containers, capture PNGs
# all build + run (containers must already exist: run `setup` first)
# teardown stop + remove only the containers/network/image created by `setup`
# The integration-test app is built once with the real HOME (flutter tool needs
# it), then the built binary is launched directly with HOME=<temp demo home>.
# Env: SECTIONS="01,02,..." limits the sections; DOCS_OUT overrides the output dir.
# Env: SECTIONS="01,02,..." limits sections; MODES="desktop mobile" picks launches;
# DOCS_OUT overrides the output dir; DOCS_KEY_DIR holds the generated client key
# (default ~/.local/state/yourssh-docs-journey, never inside the repo).
# DOCS_PREFIX (default yourssh-docs) names containers/network/image;
# SSH_PORT/BASTION_PORT/RDP_PORT/VNC_PORT override host ports. The app harness
# expects the defaults 2222/2223/3389/5900, so override them only to test setup.
set -euo pipefail
export PATH="$HOME/development/flutter/bin:$PATH"
command -v flutter >/dev/null 2>&1 || export PATH="$HOME/development/flutter/bin:$PATH"
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
MODE="${1:-all}"
OUT="${DOCS_OUT:-$ROOT/screenshots/docs}"
PREFIX="${DOCS_PREFIX:-yourssh-docs}"
SSH_PORT="${SSH_PORT:-2222}"; BASTION_PORT="${BASTION_PORT:-2223}"
RDP_PORT="${RDP_PORT:-3389}"; VNC_PORT="${VNC_PORT:-5900}"
KEY_DIR="${DOCS_KEY_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/yourssh-docs-journey}"
KEY="$KEY_DIR/client_ed25519"
NET="$PREFIX-net"; IMAGE="$PREFIX-ssh:latest"
CONTAINERS=("$PREFIX-ssh" "$PREFIX-bastion" "$PREFIX-db" "$PREFIX-rdp" "$PREFIX-vnc")

is_running() { [[ "$(docker container inspect -f '{{.State.Running}}' "$1" 2>/dev/null)" == true ]]; }
exists() { docker container inspect "$1" >/dev/null 2>&1; }
ensure() { # name, then `docker run` args: reuse a running one, start a stopped one, else create
local n="$1"; shift
if is_running "$n"; then echo "reuse running $n"
elif exists "$n"; then echo "start $n"; docker start "$n" >/dev/null
else echo "create $n"; docker run -d --name "$n" "$@" >/dev/null; fi
}

setup() {
mkdir -p "$KEY_DIR"; chmod 700 "$KEY_DIR"
[[ -f "$KEY" ]] || ssh-keygen -q -t ed25519 -N '' -C yourssh-docs-demo -f "$KEY"
docker build -q -t "$IMAGE" "$ROOT/tool/docs_journey" >/dev/null
docker network inspect "$NET" >/dev/null 2>&1 || docker network create "$NET" >/dev/null
ensure "$PREFIX-ssh" --network "$NET" --network-alias yourssh-demo --hostname yourssh-demo -p "127.0.0.1:$SSH_PORT:22" "$IMAGE"
ensure "$PREFIX-bastion" --network "$NET" --network-alias bastion --hostname bastion -p "127.0.0.1:$BASTION_PORT:22" "$IMAGE"
ensure "$PREFIX-db" --network "$NET" --network-alias db-internal --hostname db-internal "$IMAGE"
local c
for c in ssh bastion db; do # install the client public key (idempotent overwrite)
docker exec -i "$PREFIX-$c" sh -c 'cat > /home/demo/.ssh/authorized_keys && chown demo:demo /home/demo/.ssh/authorized_keys && chmod 600 /home/demo/.ssh/authorized_keys' < "$KEY.pub"
done
ensure "$PREFIX-rdp" --hostname win-demo -p "127.0.0.1:$RDP_PORT:3389" scottyhardy/docker-remote-desktop:latest
ensure "$PREFIX-vnc" -e VNC_PW=demo12345 -p "127.0.0.1:$VNC_PORT:5900" dorowu/ubuntu-desktop-lxde-vnc:latest
# RDP login demo / demo12345 (idempotent)
for _ in $(seq 1 20); do docker exec "$PREFIX-rdp" true 2>/dev/null && break; sleep 1; done
docker exec "$PREFIX-rdp" bash -c "id demo >/dev/null 2>&1 || useradd -m -s /bin/bash demo; echo 'demo:demo12345' | chpasswd"
echo "setup done. client key: $KEY (host ports ssh=$SSH_PORT bastion=$BASTION_PORT rdp=$RDP_PORT vnc=$VNC_PORT)"
}

teardown() {
local c
for c in "${CONTAINERS[@]}"; do exists "$c" && { docker rm -f "$c" >/dev/null; echo "removed $c"; }; done
docker network inspect "$NET" >/dev/null 2>&1 && { docker network rm "$NET" >/dev/null; echo "removed network $NET"; }
docker image inspect "$IMAGE" >/dev/null 2>&1 && { docker rmi "$IMAGE" >/dev/null; echo "removed image $IMAGE"; }
echo "teardown done (client key in $KEY_DIR kept; delete it manually if unwanted)"
}

case "$MODE" in
setup) setup; exit 0 ;;
teardown) teardown; exit 0 ;;
build|run|all) ;;
*) echo "usage: $0 [setup|build|run|all|teardown]" >&2; exit 2 ;;
esac
RUN_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/yourssh-docs-run.XXXXXX")"
DEMO_HOME="$RUN_ROOT/yourssh-docs-home"
KEY="${DEMO_KEY:-/private/tmp/claude-501/-Users-thangnm-Documents-Personal/249a95bd-233f-499c-b54b-eb14f3c0d9dd/scratchpad/journey/sshd/client_ed25519}"

if [[ "$MODE" == build || "$MODE" == all ]]; then
(cd "$ROOT/app" && flutter build macos --debug -t integration_test/docs_journey_test.dart)
fi
[[ "$MODE" == build ]] && exit 0
[[ -f "$KEY" ]] || { echo "no client key at $KEY: run '$0 setup' first" >&2; exit 1; }
for c in "${CONTAINERS[@]}"; do is_running "$c" || { echo "$c is not running: run '$0 setup' first" >&2; exit 1; }; done

APP="$ROOT/app/build/macos/Build/Products/Debug/yourssh.app/Contents/MacOS/yourssh"
[[ -x "$APP" ]] || APP="$(ls "$ROOT"/app/build/macos/Build/Products/Debug/*.app/Contents/MacOS/* | head -1)"
Expand Down
19 changes: 19 additions & 0 deletions tool/docs_journey/Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Demo SSH server image for the docs screenshot journey (see tool/docs_journey.sh).
# No secrets baked in: the client public key is installed at `setup` time.
# The demo/demo1234 password is a throwaway for a loopback-only demo container.
FROM alpine:latest
RUN apk add --no-cache openssh bash python3 py3-aiosmtpd htop git curl less vim tmux ncurses \
&& ssh-keygen -A \
&& adduser -D -s /bin/bash demo && echo 'demo:demo1234' | chpasswd \
&& mkdir -p /home/demo/.ssh /home/demo/projects/webapp/src /home/demo/logs /home/demo/backups \
&& printf 'server {\n listen 80;\n server_name demo.local;\n}\n' > /home/demo/projects/webapp/nginx.conf \
&& printf '# Web app\n\nDemo project used in the YourSSH docs.\n' > /home/demo/projects/webapp/README.md \
&& printf 'console.log("hello from yourssh-demo");\n' > /home/demo/projects/webapp/src/index.js \
&& for i in 1 2 3; do echo "2026-11-1$i 10:0$i:00 INFO request served in ${i}2ms" >> /home/demo/logs/app.log; done \
&& head -c 2097152 /dev/urandom > /home/demo/backups/db-2026-11-12.sql.gz \
&& printf 'export PS1="\\[\\e[1;32m\\]\\u@\\h\\[\\e[0m\\]:\\[\\e[1;34m\\]\\w\\[\\e[0m\\]\\$ "\nalias ll="ls -la"\n' > /home/demo/.bashrc \
&& printf '[ -f ~/.bashrc ] && . ~/.bashrc\n' > /home/demo/.bash_profile \
&& chown -R demo:demo /home/demo && chmod 700 /home/demo/.ssh \
&& sed -i 's/^#\?PasswordAuthentication.*/PasswordAuthentication yes/; s/^#\?AllowTcpForwarding.*/AllowTcpForwarding yes/; s/^#\?AllowAgentForwarding.*/AllowAgentForwarding yes/; s/^#\?GatewayPorts.*/GatewayPorts no/' /etc/ssh/sshd_config
EXPOSE 22
CMD ["/usr/sbin/sshd","-D","-e"]
Loading