diff --git a/.claude/skills/yourssh-screenshots/SKILL.md b/.claude/skills/yourssh-screenshots/SKILL.md index 9675eb7a..9f6c9667 100644 --- a/.claude/skills/yourssh-screenshots/SKILL.md +++ b/.claude/skills/yourssh-screenshots/SKILL.md @@ -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//`, 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//.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 --out ` (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 `` (2-column `` 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 @@ -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 @@ -88,28 +114,7 @@ app-lock is force-disabled in setup because an emulator has no enrolled fingerpr 5. Run the test to verify 6. Add the `` 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 `
` with 2-column rows: - -```html -### Group Name -
- - - - -
Screen Title
Screen Title
-``` - -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 @@ -117,7 +122,7 @@ done - **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 | |---|---| diff --git a/tool/docs_journey.sh b/tool/docs_journey.sh index a5e24e4b..e811accf 100755 --- a/tool/docs_journey.sh +++ b/tool/docs_journey.sh @@ -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=. -# 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)" diff --git a/tool/docs_journey/Dockerfile b/tool/docs_journey/Dockerfile new file mode 100644 index 00000000..99e7a736 --- /dev/null +++ b/tool/docs_journey/Dockerfile @@ -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"]