# 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).