zhaolei
3c72efcb7f
Some checks failed
build-packages / resolve bundled mosh-client (push) Has been cancelled
build-packages / resolve bundled et-client (push) Has been cancelled
build-packages / build-macos (push) Has been cancelled
build-packages / build-windows (push) Has been cancelled
build-packages / build-linux-x64 (push) Has been cancelled
build-packages / build-linux-arm64 (push) Has been cancelled
build-packages / release (push) Has been cancelled
build-packages / update Nix release metadata (push) Has been cancelled
build-packages / bump homebrew tap (push) Has been cancelled
test / lint-and-test (push) Has been cancelled
AI automation / Route event (push) Has been cancelled
AI automation / Hand reopened issue to maintainers (push) Has been cancelled
AI automation / Clean source issue state (push) Has been cancelled
AI automation / Reconcile handoffs (push) Has been cancelled
AI automation / Classify issue (push) Has been cancelled
AI automation / Claude Code smoke (push) Has been cancelled
AI automation / Review issue follow-up (push) Has been cancelled
AI automation / Publish issue follow-up (push) Has been cancelled
AI automation / Implement with Claude Code (push) Has been cancelled
AI automation / Publish implement PR (push) Has been cancelled
AI automation / Continue queued issue comments (push) Has been cancelled
AI automation / Codex review loop (push) Has been cancelled
AI automation / Publish Codex fix (push) Has been cancelled
AI automation / Clear Codex dispatch marker (push) Has been cancelled
AI automation / Own PR re-request Codex (push) Has been cancelled
AI automation / External PR re-request Codex (push) Has been cancelled
AI automation / Poll Codex reaction / retry (push) Has been cancelled
build-et-binaries / build-linux-x64 (push) Has been cancelled
build-et-binaries / build-linux-arm64 (push) Has been cancelled
build-et-binaries / build-macos-universal (push) Has been cancelled
build-et-binaries / build-windows-x64 (push) Has been cancelled
build-et-binaries / release (push) Has been cancelled
73 lines
3.3 KiB
Markdown
73 lines
3.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Start dev server (runs lint first, then Vite + Electron concurrently)
|
|
npm run dev
|
|
|
|
# Lint
|
|
npm run lint
|
|
npm run lint:fix
|
|
|
|
# Run all tests
|
|
npm test
|
|
|
|
# Run a single test file
|
|
node --test --import tsx path/to/file.test.ts
|
|
|
|
# Build renderer
|
|
npm run build
|
|
|
|
# Package for current platform
|
|
npm run pack
|
|
|
|
# Package for specific platforms
|
|
npm run pack:mac
|
|
npm run pack:win
|
|
npm run pack:linux
|
|
```
|
|
|
|
## Architecture
|
|
|
|
Netcatty is an Electron + React desktop app (SSH manager, terminal, SFTP browser). It has two runtimes:
|
|
|
|
### Electron Main Process (`electron/`)
|
|
- **`main.cjs`** — entry point; wires crash logging, process error guards, and delegates to `main/registerBridges.cjs`
|
|
- **`bridges/`** — one `.cjs` file per capability domain (sshBridge, sftpBridge, terminalBridge, portForwardingBridge, aiBridge, etc.). Each bridge exposes IPC handlers via `ipcMain`. Tests live alongside the bridge file (`*.test.cjs`).
|
|
- **`preload.cjs`** — exposes a typed `window.electron` API to the renderer via `contextBridge`. Uses `preload/api.cjs` for the generated API surface.
|
|
- **`cli/`** — `netcatty-tool-cli.cjs` is a separate internal binary for tool/MCP integration; treat as internal surface only.
|
|
|
|
### Renderer Process (React + Vite)
|
|
Three-layer architecture (see `AGENTS.md` for full detail):
|
|
|
|
- **`domain/`** — pure TypeScript logic, no side effects. Models (`models.ts`), host helpers, workspace tree operations.
|
|
- **`application/state/`** — React hooks that own state and persistence boundaries. Key hooks: `useVaultState` (hosts/keys/snippets), `useSessionState` (terminal sessions/workspace), `useSettingsState` (theme/config).
|
|
- **`infrastructure/`** — external edges: `persistence/localStorageAdapter.ts` for storage, `services/` for network calls (Gemini AI, GitHub Gist sync), `config/` for defaults, storage keys, and terminal themes.
|
|
- **`components/`** — presentation only. `App.tsx` wires hooks to components; no business logic in components.
|
|
|
|
### IPC Pattern
|
|
UI calls `window.electron.*` (preload API) → IPC → bridge handler in main process. Never call `ipcRenderer` directly from components.
|
|
|
|
### Key Conventions
|
|
- All storage reads/writes go through `localStorageAdapter`; storage keys are in `infrastructure/config/storageKeys.ts`.
|
|
- Temporary files must use `tempDirBridge.getTempFilePath(fileName)` — never `os.tmpdir()` directly.
|
|
- Aside panels (VaultView subpages) use the shared design system in `components/ui/aside-panel.tsx` — see `AGENTS.md` for usage patterns.
|
|
- Renderer code is TypeScript/ESM; Electron main/bridges are CommonJS (`.cjs`).
|
|
- Path alias `@/` resolves to the repo root (configured in `vite.config.ts` and `tsconfig.json`).
|
|
|
|
## Reporting Issues & PRs
|
|
|
|
Issues that skip the format gate are auto-closed. When opening issues (including via `gh` / API):
|
|
|
|
- Title must start with `[Bug]`, `[Feature]`, or `[Other]` plus a short summary.
|
|
- Body must use `.github/ISSUE_TEMPLATE/` (Bug Report or Feature Request) and fill required fields.
|
|
- PRs should follow `.github/PULL_REQUEST_TEMPLATE.md`.
|
|
|
|
See [CONTRIBUTING.md](./CONTRIBUTING.md) and the "Reporting Issues & PRs" section in [AGENTS.md](./AGENTS.md).
|