Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
5245d5e
chore: stop tracking the script engine's flutter test build output
thangnm93 Nov 13, 2026
8b58a91
chore: make docs screenshot journey reproducible (setup/teardown) and…
thangnm93 Nov 13, 2026
2df107e
Merge pull request #123 from YoursshLabs/master
thangnm93 Nov 13, 2026
f7a78a1
Merge pull request #124 from YoursshLabs/chore/untrack-engine-build
thangnm93 Nov 13, 2026
56c38ab
fix(port-forward): confirm before deleting a rule
thangnm93 Nov 13, 2026
3608cc6
fix(share): state that sessions are end-to-end encrypted with the sha…
thangnm93 Nov 13, 2026
228e49e
docs(readme): macOS builds are notarized, link user docs, describe sh…
thangnm93 Nov 13, 2026
60117f1
fix(mobile): make pair-device screen copy accurate about what syncs
thangnm93 Nov 13, 2026
e4e984b
fix(mobile): auto-lock row states the real behavior
thangnm93 Nov 13, 2026
1b51a29
fix(mobile): remove app-wide lock switch from the host form
thangnm93 Nov 13, 2026
fb43c62
fix(script-engine): expose documented ui/ssh/storage plugin globals v…
thangnm93 Nov 13, 2026
5eb0a18
fix(keys): delete stored passphrase on key removal and remember dismi…
thangnm93 Nov 13, 2026
0f4db13
chore(mobile): drop unused imports after host-form lock switch removal
thangnm93 Nov 13, 2026
c7b034b
Merge pull request #125 from YoursshLabs/chore/docs-journey-skill
thangnm93 Nov 13, 2026
599b8a8
Merge pull request #126 from YoursshLabs/fix/docs-alignment
thangnm93 Nov 13, 2026
8cf8290
fix(mobile): app lock covers every route, not just home
thangnm93 Nov 13, 2026
dc99abb
Merge pull request #127 from YoursshLabs/fix/plugin-api-docs
thangnm93 Nov 13, 2026
b188785
Merge pull request #129 from YoursshLabs/fix/app-lock-every-route
thangnm93 Nov 13, 2026
9af0f7b
Merge pull request #128 from YoursshLabs/fix/docs-alignment-2
thangnm93 Nov 13, 2026
c1588df
release: 0.4.1 — Android app-lock fix, doc-driven fixes and the docs …
thangnm93 Nov 13, 2026
832d7a4
docs(readme): Homebrew install and the signed/notarized macOS builds
thangnm93 Nov 13, 2026
c82a761
docs: the documentation site is https://yoursshlabs.com
thangnm93 Nov 13, 2026
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
22 changes: 22 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.4.1] — 2026-11-13

Security and polish fixes found while writing the documentation (now at https://yoursshlabs.com).

### Security
- **Android: the app lock now covers every screen.** The lock used to sit under any open screen, so a terminal, SFTP browser or dialog stayed visible above **YourSSH is locked** (and in the app switcher) after the app locked. The lock now covers the whole app; open screens and sessions survive the unlock.

### Fixed
- Deleting a port-forwarding rule asks **Delete rule?** first, like every other destructive action.
- Removing a key from the Keychain also deletes the passphrase YourSSH saved for it, and a removed `~/.ssh` key no longer reappears at the next launch (import it again to bring it back).
- Script plugins: the documented `ui.*`, `ssh.*` and `storage.*` globals now exist (they used to fail with `'ui' is not defined`); `ui.notify` writes to the plugin console.
- Android: the pair-device screen says what actually syncs (hosts and their passwords — not keys or snippets), the Auto-lock row describes the real behaviour (**Immediately when you leave the app**), and the misleading per-host **Unlock with biometrics** switch is gone from the host form (the app lock lives in Settings → Security).
- The terminal-sharing dialog says sessions are end-to-end encrypted with the share code (it said "Shared over TLS").

### Documentation
- New documentation site: https://yoursshlabs.com. The README's macOS section reflects that releases are signed and notarized.

### Added
- **Homebrew:** `brew install --cask yoursshlabs/tap/yourssh` (tap [YoursshLabs/homebrew-tap](https://github.com/YoursshLabs/homebrew-tap); the cask follows new releases automatically).

---

## [0.4.0] — 2026-11-13

A new look (forui "Amber Brand" design system on desktop and mobile), a `yourssh` command-line client with `yourssh://` links, and a round of fixes found by driving the finished app end to end.
Expand Down
8 changes: 4 additions & 4 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -226,10 +226,10 @@ Loaded at runtime from a plugins directory via `packages/yourssh_script_engine`.
- `PluginUiRegistry` — plugins can register Flutter widgets by calling the `ui.register(id, widgetSpec)` JS API; the app renders these in the plugin manager

**Bridges (Dart APIs exposed to JS):**
- `SshBridge` — `ssh.exec(sessionId, cmd)`, `ssh.write(sessionId, data)`
- `SftpBridge` — `sftp.list(sessionId, path)`, `sftp.readFile`, `sftp.writeFile`
- `StorageBridge` — `storage.get/set/delete(key)` (namespaced per plugin)
- `UiBridge` — `ui.showNotification(msg)`, `ui.register(id, spec)`; panel `postMessage` types handled natively in Dart (`ssh-exec`, `ssh-sessions`, `sftp-list`, `sftp-read`) enforce the same permissions as the bridges (`ssh.exec`, `session.observe`|`ssh.exec`, `sftp.read`) — a panel is plugin-controlled HTML
- Plugin globals come from a JS prelude (`_kPrelude` in `script_engine_service.dart`) that wraps the raw `_x` host functions (JSON in/out); a wrapper throws `Permission denied` when the bridge did not register the function, so `PermissionGuard` stays the only gate. Raw `_x.*` functions keep working. Documented in `docs/plugin-authoring-guide.md` section 5.
- `SshBridge` — `ssh.sessions()` (`session.observe`|`ssh.exec`); `TerminalInjectBridge` — `ssh.inject(sessionId, text)` (`terminal.inject`). No JS `ssh.exec`/`sftp` (the raw `_ssh.exec` and `_sftp.*` are stubs; use the panel messages below)
- `StorageBridge` — `storage.get/set/delete(key)` (sync, string values, namespaced per plugin, no permission)
- `UiBridge` — `ui.notify(msg, {type})` (host `onNotify`), `ui.statusbar.add/update/remove`, `ui.panel.register({title, icon, webviewEntry, onMessage})`, `ui.clipboard.copy`, `ui.addCommand` (handler not invoked yet); panel `postMessage` types handled natively in Dart (`ssh-exec`, `ssh-sessions`, `sftp-list`, `sftp-read`) enforce the same permissions as the bridges (`ssh.exec`, `session.observe`|`ssh.exec`, `sftp.read`) — a panel is plugin-controlled HTML

**UI screens:**
- `plugin_consent_dialog.dart` — shown on first load; user must accept declared permissions
Expand Down
Loading
Loading