toolhive-studio

This file provides guidance to Claude Code when working with this repository.

## Project Overview

ToolHive Studio is an Electron desktop application for managing MCP (Model Context Protocol) servers. Built with React, TypeScript, and Vite. The Electron app bundles the [ToolHive CLI](https://github.com/stacklok/toolhive) (`thv`) binary.

## Build and Development Commands

```bash
pnpm install              # Install dependencies
pnpm run start            # Start dev server with hot reload
pnpm run lint             # Run ESLint
pnpm run type-check       # TypeScript checking (both app and node configs)
pnpm run format           # Format with Prettier
pnpm run test:nonInteractive  # Run unit tests once
pnpm run test             # Run unit tests in watch mode
pnpm run test:coverage    # Unit tests with coverage
pnpm run e2e              # Package + run Playwright e2e tests
pnpm run knip             # Detect unused code
pnpm run generate-client  # Fetch OpenAPI spec + regenerate API client
```

Husky/lint-staged automatically run lint + format on staged `.ts`/`.tsx` files. Run `pnpm run type-check` manually before committing — it is not covered by the hook.

## Environment Requirements

- Node.js >=24 <25 (use `nvm use` — `.nvmrc` is present)
- pnpm package manager
- Docker daemon must be running (required by ToolHive)

## Common Gotchas

- **Docker must be running** before `pnpm run start` — ToolHive manages containers, so the daemon is required even in dev
- **Node version mismatch**: wrong Node version can break other native modules. Always `nvm use` first
- **Stale generated types**: if type errors reference API types, run `pnpm run generate-client` to refresh
- **Electron test runner**: unit tests run through Electron (`vitest:electron`), not plain Node — required for native module compatibility
- **All commands from root**: always run `pnpm` commands from the repository root, not from subdirectories

## Auto-Generated Code — Never Edit Manually

These files are generated and will be overwritten:

- **`renderer/src/route-tree.gen.ts`** — Generated by TanStack Router plugin from route files
- **`common/api/generated/*`** — Generated by `pnpm run generate-client` from OpenAPI spec

To update generated API client: edit the OpenAPI spec source, then run `pnpm run generate-client`.
To update routes: add/modify files in `renderer/src/routes/`, the route tree regenerates automatically.

## Architecture

### Electron Process Model

- **`main/`** — Main process: app lifecycle, IPC handlers, database (SQLite), auto-update, deep links, CLI integration
- **`renderer/`** — Renderer process: React UI, routing, API calls, state management
- **`preload/`** — Preload scripts: bridge between main and renderer via `window.electronAPI`
- **`common/`** — Shared code: generated API client, types, constants

### Renderer Architecture

- **Routing**: TanStack Router with file-based convention in `renderer/src/routes/`
  - `__root.tsx` — root layout
  - Route files use dot-notation for nesting (e.g., `logs.$groupName.$serverName.tsx`)
- **State**: TanStack React Query for server state, React Context for app state (theme, permissions)
- **API**: Generated client from OpenAPI spec in `common/api/generated/`
- **UI**: Radix UI primitives + Tailwind CSS + CVA for component variants
- **Forms**: React Hook Form + Zod validation

## Code Conventions

- **File naming**: always kebab-case (e.g., `card-mcp-server.tsx`, `use-auto-update.ts`)
- **Components**: PascalCase exports, functional components with hooks
- **Path aliases**: `@/*` (renderer/src), `@common/*` (common), `@utils/*` (utils), `@mocks/*` (mocks)
- **Imports**: use path aliases, not relative paths for cross-directory imports
- **Exports**: prefer named exports over default exports

## Testing

- **Unit tests**: Vitest + Testing Library + MSW for API mocking
- **Test location**: `__tests__/` directories colocated with source
- **API mocking**: Auto-generated MSW fixtures from OpenAPI spec. See `docs/mocks.md`
  - Fixtures in `renderer/src/common/mocks/fixtures/`
  - Use `.override()` / `.overrideHandler()` for test-specific responses
  - Use `recordRequests()` to assert on API calls
- **E2E tests**: Playwright in `e2e-tests/`

### Running a Single Test

```bash
pnpm run test run path/to/file.test.tsx
```

## Commit and PR Guidelines

- Follow [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`, `test:`, `chore:`, etc.
- PR titles must follow conventional commit format (validated by CI)
- Keep PRs small and focused (size/XS or size/S preferred)
- See `CONTRIBUTING.md` for full guidelines

## Deep Links

- Protocol: `toolhive-gui://v1/<intent>?<params>`
- Handled by main process, routed to TanStack Router
- See `.claude/skills/deep-links/` for implementation guidance