# Development Guidelines

This document defines project-level development rules for hermes-ui. It is tool-agnostic and applies to all contributors and coding agents.

## Prerequisites

- Node.js `>=23` (see `engines` in `package.json`).
- Python with `hermes-agent` installed. The Hermes CLI is not bundled; point
  `HERMES_BIN` at the executable or make `hermes` resolvable from `PATH`.

## Commands

```bash
npm ci --ignore-scripts
npm run dev
npm run test
npm run test:coverage
npm run test:e2e
npm run build
```

- `npm ci --ignore-scripts` installs exactly what `package-lock.json` pins. Do not upgrade dependencies.
- `npm run dev` starts the Vite client and Koa server together.
- `npm run test` runs Vitest unit tests.
- `npm run test:coverage` is what the Build workflow runs before `npm run build`.
- `npm run test:e2e` runs Playwright browser tests against a mocked BFF API.
- `npm run build` type-checks and builds both client and server.

## Architecture

- Frontend code lives under `packages/client/src`.
- Server code lives under `packages/server/src`.
- Hermes-specific client code stays under `hermes` namespaces: API modules, views, stores, and components.
- Server routes should stay thin. Put request handling in controllers and reusable behavior in services.
- The chat runtime is Socket.IO based and lives under `packages/server/src/services/hermes/run-chat`.
- Web UI state lives under `HERMES_WEB_UI_HOME` or `HERMES_WEBUI_STATE_DIR`, defaulting to `~/.hermes-web-ui`.
- Hermes `state.db` is read-only. Never open it from Node-side code.

## Coding Rules

- Prefer existing local patterns over new abstractions.
- Keep changes scoped to the requested behavior.
- Do not mix unrelated refactors into feature or bugfix commits.
- Do not reintroduce deprecated compatibility switches without a current caller.
- Use structured APIs and parsers for structured data instead of ad hoc string edits when possible.
- Add comments only where they explain non-obvious behavior or constraints.

## Frontend Rules

- Use Vue 3 Composition API with `<script setup lang="ts">`.
- Use Pinia setup stores.
- Use the shared API request helper in `packages/client/src/api/client.ts`.
- Add user-facing strings to all locale files (`zh.ts` and `en.ts` are the only two).
- Keep component styles scoped with SCSS unless the style is intentionally global.
- Use Arco Design Vue components and follow existing Arco patterns. Do not add new `naive-ui` imports
  and do not introduce another UI library.

## Server Rules

- Register local API routes before proxy catch-all routes.
- Keep auth behavior centralized in `packages/server/src/services/auth.ts`.
- Use `config.appHome` for Web UI state paths.
- Keep Hermes home paths separate from Web UI home paths.
- Use `getActiveProfileDir()` or related profile helpers for Hermes profile files.
- Avoid shell string construction for CLI calls; prefer `execFile`/`spawn` with argument arrays,
  routed through `execHermesWithBin`/`spawnHermesWithBin`.

## Red Lines

- `packages/server/src/services/hermes/agent-bridge/python/` is vendored and read-only. The
  `HERMES_DESKTOP` checks in `bridge_runtime.py` are the one exception and must stay.
- The `/chat-run` Socket.IO event contract is frozen: no changes to event names, field names,
  field types, or emission timing. Adding optional fields is allowed.
- Changes under `services/hermes/group-chat/`, `lib/context-compressor/`, or
  `services/hermes/context-engine/` require a `docs/chat-chain-changes/<date>-<slug>.md` fragment.

## Testing Rules

- Add focused Vitest coverage for server and store logic changes.
- Add Playwright coverage for browser-visible flows and routing/auth regressions.
- For frontend browser tests, prefer API/socket mocks over real external services.
- Before opening a PR, run the smallest relevant tests plus `npm run build`.
- For broad changes, run:

```bash
npm run test:coverage
npm run test:e2e
npm run build
```

## Commit And PR Rules

- Branch from `main` for new work.
- Use short, descriptive branch names such as `fix/login-token` or `feat/group-chat-copy`.
- Commit only files that belong to the change.
- Use concise commit messages that describe the change, for example `fix login token storage` or `add group chat clone naming`.
- Keep commits focused. Do not bundle unrelated cleanup with feature work unless the cleanup is required.
- Push the branch and open a PR against `main` unless the issue explicitly targets another base.
- Prefer draft PRs while validation is still running or when the change needs review before merge.
- Mark a PR ready only after the relevant tests and build pass.
- Keep PR titles concrete and scoped, for example `make Web UI state directory configurable`.
- Link issues in the PR body with `Closes #123`, `Fixes #123`, or `Refs #123` as appropriate.
- PR descriptions should include:
  - what changed
  - why it changed
  - user or developer impact
  - validation commands run
  - known limitations or follow-up work, if any
- Do not overwrite or revert unrelated user changes.

Use this PR body shape by default:

```md
## Summary
- ...
- ...

Closes #123

## Validation
- `npm run test:coverage`
- `npm run build`
```