155 lines
4.4 KiB
Markdown
155 lines
4.4 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Repository layout (high level)
|
||
|
||
- `mengyaconnect-backend/` — Go (Gin) HTTP + WebSocket server that:
|
||
- exposes a WebSocket SSH “bridge” (`/api/ws/ssh`) backed by `golang.org/x/crypto/ssh`
|
||
- persists SSH profiles / quick commands / scripts to the local filesystem under `data/`
|
||
- `mengyaconnect-frontend/` — Vite + Vue 3 single-page UI using `xterm.js` to render terminals and talk to the backend WebSocket.
|
||
|
||
There is no top-level build system; run commands inside each subproject directory.
|
||
|
||
## Common development commands
|
||
|
||
### Backend (Go)
|
||
|
||
Run the server (default `:8080`):
|
||
|
||
```sh
|
||
cd mengyaconnect-backend
|
||
go run .
|
||
```
|
||
|
||
Build a local binary:
|
||
|
||
```sh
|
||
cd mengyaconnect-backend
|
||
go build -o mengyaconnect-backend
|
||
```
|
||
|
||
Basic checks (no dedicated lint/test tooling is configured beyond standard Go tools):
|
||
|
||
```sh
|
||
cd mengyaconnect-backend
|
||
go fmt ./...
|
||
go test ./...
|
||
# run a single Go test (if/when tests exist)
|
||
go test -run TestName ./...
|
||
```
|
||
|
||
### Frontend (Vite + Vue)
|
||
|
||
Install deps (repo includes `package-lock.json`):
|
||
|
||
```sh
|
||
cd mengyaconnect-frontend
|
||
npm install
|
||
```
|
||
|
||
Run dev server (default `http://localhost:5173`):
|
||
|
||
```sh
|
||
cd mengyaconnect-frontend
|
||
npm run dev
|
||
```
|
||
|
||
Build + preview:
|
||
|
||
```sh
|
||
cd mengyaconnect-frontend
|
||
npm run build
|
||
npm run preview
|
||
```
|
||
|
||
## Backend architecture (mengyaconnect-backend)
|
||
|
||
**Single-file server:** Almost all backend logic lives in `mengyaconnect-backend/main.go`.
|
||
|
||
### HTTP routes
|
||
|
||
Defined in `main.go` near the top:
|
||
|
||
- `GET /health` — basic health check.
|
||
- `GET /api/ws/ssh` — WebSocket endpoint for interactive SSH.
|
||
- SSH profile CRUD:
|
||
- `GET /api/ssh`
|
||
- `POST /api/ssh`
|
||
- `PUT /api/ssh/:name`
|
||
- `DELETE /api/ssh/:name`
|
||
- Quick command CRUD (stored as an array; updates by index):
|
||
- `GET /api/commands`
|
||
- `POST /api/commands`
|
||
- `PUT /api/commands/:index`
|
||
- `DELETE /api/commands/:index`
|
||
- Script CRUD (stored as files):
|
||
- `GET /api/scripts`
|
||
- `GET /api/scripts/:name`
|
||
- `POST /api/scripts`
|
||
- `PUT /api/scripts/:name`
|
||
- `DELETE /api/scripts/:name`
|
||
|
||
Response convention is typically `{ "data": ... }` on success and `{ "error": "..." }` on failure.
|
||
|
||
### Persistence model (filesystem)
|
||
|
||
All persisted state is stored under a base directory:
|
||
|
||
- base: `DATA_DIR` env var, default `data/`
|
||
- SSH profiles: `data/ssh/*.json`
|
||
- commands list: `data/command/command.json`
|
||
- scripts: `data/script/<name>`
|
||
|
||
`sanitizeName()` is used for path-safety (prevents `../` traversal by forcing `filepath.Base`).
|
||
|
||
Note: the repo currently contains example data files under `mengyaconnect-backend/data/` (including SSH profiles). Treat these as sensitive and rotate/remove before sharing the repository.
|
||
|
||
### WebSocket SSH bridge
|
||
|
||
The backend upgrades `/api/ws/ssh` and uses a simple JSON message protocol (`wsMessage` in `main.go`).
|
||
|
||
Client → server message types:
|
||
- `connect`: `{ host, port, username, password? | privateKey? , passphrase?, cols, rows }`
|
||
- `input`: `{ data }` (raw terminal input)
|
||
- `resize`: `{ cols, rows }`
|
||
- `ping`
|
||
- `close`
|
||
|
||
Server → client message types:
|
||
- `status`: `{ status, message }` (e.g. connected/ready/closing/closed)
|
||
- `output`: `{ data }` (stdout/stderr bytes as text)
|
||
- `error`: `{ message }`
|
||
- `pong`
|
||
|
||
SSH implementation notes:
|
||
- PTY is requested as `xterm-256color`.
|
||
- Host key verification is currently disabled via `ssh.InsecureIgnoreHostKey()`.
|
||
|
||
### Backend configuration (env)
|
||
|
||
- `PORT` (default `8080`) or `ADDR` (default `:<PORT>`)
|
||
- `DATA_DIR` (default `data`)
|
||
- `GIN_MODE` (if set, passed to `gin.SetMode`)
|
||
- `ALLOWED_ORIGINS` (comma-separated) is used by the WebSocket upgrader `CheckOrigin`.
|
||
|
||
## Frontend architecture (mengyaconnect-frontend)
|
||
|
||
**Single-screen UI:** Most logic is in `mengyaconnect-frontend/src/App.vue`.
|
||
|
||
- Uses `@xterm/xterm` + `@xterm/addon-fit`.
|
||
- Supports multiple concurrent sessions via tabs (each tab owns its own `WebSocket` + `Terminal`).
|
||
- Terminal input is forwarded to the backend as `{ type: "input", data }`.
|
||
- Resize events are forwarded as `{ type: "resize", cols, rows }`.
|
||
|
||
### Frontend configuration (Vite env)
|
||
|
||
`wsUrl` is computed in `App.vue`:
|
||
|
||
- If `VITE_WS_URL` is set, it is used as the full WebSocket URL.
|
||
- Otherwise it builds `${ws|wss}://${window.location.hostname}:${VITE_WS_PORT||8080}/api/ws/ssh`.
|
||
|
||
In development, you’ll usually run:
|
||
- backend on `localhost:8080`
|
||
- frontend on `localhost:5173`
|