JRedisDesktop/AGENTS.md

# AGENTS.md — JRedisDesktop v2

## Project identity

Fork of [AnotherRedisDesktopManager](https://github.com/qishibo/AnotherRedisDesktopManager). The legacy Vue 2 codebase lives in `legacy/` and is gitignored. Work only in the root project.

## Stack

- **Shell:** Electron 33 (`src/main/index.ts`)
- **Preload:** `src/preload/index.ts` (contextBridge, typed API)
- **Renderer:** Vue 3 + Pinia + Element Plus + Vue Router (`src/renderer/`)
- **Build:** electron-vite + Vite 6 + TypeScript 5
- **Redis client:** ioredis 5 (main process only)
- **Persistence:** electron-store + safeStorage (credentials)

## Commands

```bash
npm run dev            # electron-vite dev (HMR, renderer on :5173)
npm run build          # production build → out/
npm start              # preview built app
npm run build:unpack   # build + electron-builder --dir
npm run build:win      # build + electron-builder --win
npm run build:mac      # build + electron-builder --mac
npm run build:linux    # build + electron-builder --linux
```

## Architecture

```
Electron main (src/main/)
  ├── index.ts           # Window creation, app lifecycle
  ├── redis-service.ts   # ioredis wrapper (connect, scan, CRUD, stream)
  ├── store.ts           # electron-store (connections, settings)
  ├── credential.ts      # safeStorage encrypt/decrypt
  ├── win-state.ts       # window position persistence
  └── ipc-handlers.ts    # all IPC channel handlers

Preload (src/preload/)
  ├── index.ts           # contextBridge.exposeInMainWorld
  └── index.d.ts         # ElectronAPI type declarations

Renderer (src/renderer/src/)
  ├── main.ts            # Vue 3 bootstrap (Pinia, Element Plus)
  ├── App.vue            # Shell layout (TitleBar + Sidebar + MainArea + StatusBar)
  ├── stores/
  │   ├── app.ts         # theme, fontSize, scanCount
  │   ├── connection.ts  # connections CRUD, connect/disconnect, health check
  │   └── key.ts         # key list, scan, tree view, selected key data
  ├── components/
  │   ├── TitleBar.vue       # window controls
  │   ├── StatusBar.vue      # connection status, DB selector
  │   ├── Sidebar.vue        # keyboard shortcuts, dialog host
  │   ├── ConnectionList.vue # search, import/export, new button
  │   ├── ConnectionCard.vue # single connection card
  │   ├── NewConnectionDialog.vue # create/edit/test connection
  │   ├── DbSelector.vue     # database 0-15 dropdown
  │   ├── MainArea.vue       # tab host (Status/Keys/CLI/SlowLog/Settings)
  │   ├── StatusView.vue     # INFO dashboard with stat cards
  │   ├── KeyBrowser.vue     # split pane (KeyList + KeyDetail)
  │   ├── KeyList.vue        # pattern search, filter, SCAN, multi-select
  │   ├── KeyDetail.vue      # type dispatch, TTL, rename, copy
  │   ├── StringEditor.vue   # view/edit with JSON format
  │   ├── HashEditor.vue     # field table CRUD
  │   ├── ListEditor.vue     # paginated elements
  │   ├── SetEditor.vue      # member list
  │   ├── ZsetEditor.vue     # sorted set with scores
  │   ├── StreamEditor.vue   # stream entries
  │   ├── CliView.vue        # interactive terminal
  │   ├── SlowLogView.vue    # slow log table
  │   └── SettingsView.vue   # theme, language, scan count
  ├── i18n/
  │   ├── index.ts           # useI18n composable
  │   └── locales/
  │       ├── en.ts          # English
  │       └── zh-CN.ts       # 中文
  └── composables/
      └── useKeyboard.ts     # keyboard shortcut handler
```

## IPC Channels

| Channel | Type | Purpose |
|---------|------|---------|
| `redis:connect` | invoke | Create Redis connection |
| `redis:disconnect` | invoke | Close connection |
| `redis:execute` | invoke | Execute arbitrary command |
| `redis:ping` | invoke | Health check ping |
| `redis:isConnected` | invoke | Check connection status |
| `redis:scanKeys` | invoke | SCAN with pattern |
| `redis:getString` | invoke | GET string value |
| `redis:setString` | invoke | SET string value |
| `redis:hashScan` | invoke | HSCAN fields |
| `redis:hashSet` | invoke | HSET field |
| `redis:hashDel` | invoke | HDEL field |
| `redis:listRange` | invoke | LRANGE elements |
| `redis:listPush` | invoke | RPUSH elements |
| `redis:setMembers` | invoke | SMEMBERS |
| `redis:zsetRange` | invoke | ZRANGE with scores |
| `redis:streamRange` | invoke | XRANGE entries |
| `redis:streamAdd` | invoke | XADD entry |
| `redis:batchDelete` | invoke | Pipeline DEL multiple keys |
| `redis:renameKey` | invoke | RENAME key |
| `redis:setTTL` | invoke | EXPIRE/PERSIST |
| `redis:selectDb` | invoke | SELECT database |
| `redis:dbSize` | invoke | DBSIZE |
| `redis:slowLogGet` | invoke | SLOWLOG GET |
| `redis:memoryUsage` | invoke | MEMORY USAGE |
| `storage:getConnections` | invoke | Read connections |
| `storage:saveConnection` | invoke | Save connection |
| `storage:deleteConnection` | invoke | Delete connection |
| `credential:encrypt` | invoke | safeStorage encrypt |
| `credential:decrypt` | invoke | safeStorage decrypt |
| `dialog:openFile` | invoke | Open file picker |
| `theme:get` | invoke | Get OS dark mode |
| `theme:set` | send | Set theme source |
| `window:minimize` | send | Minimize window |
| `window:maximize` | send | Toggle maximize |
| `window:close` | send | Close window |

## Keyboard Shortcuts

| Shortcut | Action | Scope |
|----------|--------|-------|
| `Ctrl+N` | New connection | Global |
| `Ctrl+R` | Refresh keys | Global |
| `F5` | Refresh keys | Global |
| `Delete` | Delete selected key | Global |
| `Escape` | Deselect key | Global |

## Build config

- `electron.vite.config.ts` defines three build targets: main, preload, renderer
- Renderer dev server runs on port 5173
- Main/preload use `externalizeDepsPlugin()` to keep node_modules external

## TypeScript

- Root `tsconfig.json` references `tsconfig.node.json` (main + preload) and `tsconfig.web.json` (renderer)
- Node target includes `src/main/**/*`, `src/preload/**/*`, `electron.vite.config.ts`
- Web target includes `src/renderer/**/*`
- `@renderer` alias resolves to `src/renderer/src`

## Security

- `contextIsolation: true` — renderer has zero Node.js access
- `nodeIntegration: false` — no Node globals in renderer
- `safeStorage` — OS-level encryption for credentials
- All Redis operations go through typed IPC to main process

## Legacy

The `legacy/` directory contains the old Vue 2 + Webpack 4 codebase. It is gitignored and not part of the v2 build. See `legacy/AGENTS.md` for its documentation.