47fb066f1d
Some checks failed
Build & Sign Wraith / Build Windows + Sign (push) Has been cancelled
CLAUDE.md for future XOs: tech stack, architecture, commands, key design decisions, lineage from Go version. GO_MIGRATION.md: step-by-step checklist for deploying v2, archiving Go repo, configuring CI secrets, first release. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
73 lines
3.7 KiB
Markdown
73 lines
3.7 KiB
Markdown
# CLAUDE.md — Wraith Desktop v2
|
|
|
|
## Project Overview
|
|
|
|
Wraith is a native desktop SSH/SFTP/RDP client — a MobaXTerm replacement. Rust backend (Tauri v2) + Vue 3 frontend (WebView2). Single binary, no Docker, no sidecar processes.
|
|
|
|
**Name:** Wraith — exists everywhere, all at once.
|
|
|
|
## Tech Stack
|
|
|
|
- **Runtime:** Tauri v2 (stable)
|
|
- **Backend:** Rust with `russh` (SSH/SFTP), `ironrdp` (RDP), `rusqlite` (SQLite), `aes-gcm` + `argon2` (vault), `dashmap` (concurrent session registry)
|
|
- **Frontend:** Vue 3 (Composition API, `<script setup>`), TypeScript, Vite, Pinia, Tailwind CSS v4, xterm.js 6, CodeMirror 6
|
|
- **Distribution:** Tauri bundler (NSIS installer), auto-updater with code signing
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src-tauri/ # Rust backend
|
|
src/
|
|
main.rs # Entry point
|
|
lib.rs # App state, module declarations, Tauri setup
|
|
ssh/ # SSH service (russh), host keys (TOFU), CWD tracker
|
|
sftp/ # SFTP operations (russh-sftp)
|
|
rdp/ # RDP service (ironrdp), scancode mapping
|
|
vault/ # Encryption (Argon2id + AES-256-GCM)
|
|
db/ # SQLite (rusqlite), migrations
|
|
connections/ # Connection CRUD, groups, search
|
|
credentials/ # Credential CRUD, encrypted storage
|
|
settings/ # Key-value settings
|
|
theme/ # Terminal themes (7 built-in)
|
|
session/ # Session manager (DashMap)
|
|
workspace/ # Workspace snapshots, crash recovery
|
|
commands/ # Tauri command wrappers
|
|
|
|
src/ # Vue 3 frontend
|
|
layouts/ # MainLayout, UnlockLayout
|
|
components/ # UI components
|
|
composables/ # useTerminal, useSftp, useRdp, useTransfers
|
|
stores/ # Pinia stores (app, session, connection)
|
|
assets/ # CSS, images
|
|
```
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
npm install # Install frontend deps
|
|
npm run dev # Vite dev server only
|
|
cargo tauri dev # Full app (Rust + frontend)
|
|
cargo tauri build # Production build
|
|
cd src-tauri && cargo test # Run Rust tests (52 tests)
|
|
cd src-tauri && cargo build # Build Rust only
|
|
```
|
|
|
|
## Architecture
|
|
|
|
- **Sessions use DashMap** — lock-free concurrent access, no deadlocks during tab detach
|
|
- **Drop trait for cleanup** — SSH/SFTP/RDP connections close automatically when sessions drop
|
|
- **CWD following via exec channel** — polls `pwd` on a separate SSH channel every 2 seconds. Never touches the terminal data stream. This avoids ANSI escape sequence corruption.
|
|
- **RDP runs in dedicated thread** — ironrdp's trait objects aren't Send, so each RDP session gets its own tokio runtime in a std::thread
|
|
- **xterm.js font handling** — `document.fonts.ready.then(() => fitAddon.fit())` prevents cell width miscalculation
|
|
|
|
## Key Design Decisions
|
|
|
|
1. **No terminal stream processing.** The Go version's CWD tracker parsed OSC 7 from the terminal output and corrupted ANSI sequences. Never again.
|
|
2. **Tauri v2 over Wails v3.** Wails v3 is alpha with breaking changes. Tauri v2 is stable with built-in multi-window, auto-updater, and active community.
|
|
3. **ironrdp over FreeRDP FFI.** Pure Rust, no DLL dependency, memory safe. FreeRDP is the fallback discussion if ironrdp can't hit performance targets.
|
|
4. **Fresh vault, no Go migration.** 6 connections — faster to re-enter than engineer format compatibility.
|
|
|
|
## Lineage
|
|
|
|
This is a ground-up Rust rewrite of `wraith` (Go/Wails v3). The Go version is archived at `wraith-go-legacy`. The original design spec is at `docs/superpowers/specs/2026-03-17-wraith-desktop-design.md` in the Go repo.
|