# Yonexus.Client — Development Conventions

This document defines implementation conventions for the client repository.

## 1. Naming Conventions

### Files
- use `camelCase.ts` for source files
- use descriptive module names matching responsibility
- avoid generic names like `utils.ts` unless the scope is extremely narrow and justified

Examples:
- `localState.ts`
- `keys.ts`
- `heartbeat.ts`
- `onGatewayStart.ts`

### Types / Interfaces
- use `PascalCase`

Examples:
- `LocalClientState`
- `ClientRuntimeState`
- `AuthProofPayload`

### Functions
- use `camelCase`

Examples:
- `loadLocalState`
- `signProofPayload`
- `startHeartbeatLoop`

### Constants
- use `UPPER_SNAKE_CASE` for exported constants

Examples:
- `HEARTBEAT_INTERVAL_MS`
- `RECONNECT_MAX_DELAY_MS`

---

## 2. Module Boundaries

### `plugin/index.ts`
- wiring only
- no business logic

### `plugin/core/`
- reusable domain logic
- local state handling
- key generation/signing
- pairing/auth/heartbeat rules
- dispatch behavior

### `servers/`
- runtime/service bootstrap code
- WebSocket client lifecycle
- reconnect/backoff orchestration

### `plugin/hooks/`
- OpenClaw lifecycle integration
- should call into core/runtime modules, not reimplement logic

### `plugin/tools/`
- thin wrappers over core/runtime capabilities
- no duplication of business rules already implemented in core

### `plugin/commands/`
- operator-facing orchestration layer
- should not directly mutate local state bypassing core rules

---

## 3. Error Conventions

### Error Shape
Use structured errors rather than throwing untyped strings.

Recommended shape:

```ts
interface YonexusClientError extends Error {
  code: string;
  details?: Record<string, unknown>;
}
```

### Error Code Style
- uppercase snake case
- stable once published in logs/tools/docs

Examples:
- `INVALID_CONFIG`
- `CONNECTION_FAILED`
- `AUTH_FAILED`
- `NOT_AUTHENTICATED`

### Error Messages
- concise
- operator-readable
- do not leak secrets, private keys, raw proofs, or unsafe internal details

---

## 4. Logging Conventions

### General Rule
Logs should help operators debug connection/auth issues without exposing secrets.

### Must Never Log in Plaintext
- `notifyBotToken`
- local `secret`
- private key material
- raw signed proof payload
- human-provided pairing code

### Preferred Log Fields
When possible, log structured context such as:
- `identifier`
- event type
- connection state transition
- reason code
- timestamp

### Example Good Logs
- `connecting to mainHost for identifier=client-a`
- `auth failed identifier=client-a reason=STALE_TIMESTAMP`
- `heartbeat loop started identifier=client-a`

---

## 5. Protocol Usage Conventions

- treat `protocol/` submodule as the source of truth
- do not implement local protocol deviations without updating `Yonexus.Protocol`
- if client behavior reveals a protocol gap, fix protocol docs rather than hiding the difference in client-only logic

---

## 6. Local State Conventions

- keep persisted local state explicit and versionable
- separate long-lived trust data from transient connection runtime state
- avoid implicit mutation of local state from multiple unrelated modules
- persist changes through explicit state APIs rather than ad-hoc file writes

---

## 7. Reconnect Conventions

- reconnect behavior should be explicit and observable
- use bounded backoff
- stop background timers cleanly on disconnect
- avoid overlapping reconnect attempts

---

## 8. Pairing / Auth Conventions

- treat pairing, auth, and re-pair transitions as explicit states
- do not silently reuse stale secrets after `re_pair_required`
- proof construction and signing should be deterministic and testable
- keep signing and local key handling isolated in dedicated modules

---

## 9. Command / Tool Conventions

- commands and tools should surface operator-safe summaries
- commands should call core/runtime services, not modify raw state directly
- sending before authentication should fail clearly unless explicit queueing is designed later

---

## 10. Testing Conventions

- write unit tests for local state, signing, and routing first
- reserve integration tests for connection/pairing/auth flows
- test negative paths deliberately:
  - connection failure
  - invalid auth response
  - forced re-pair
  - heartbeat stop/start
  - malformed builtin payload

---

## 11. Change Discipline

When implementing:
- update docs when behavior changes
- avoid silent divergence from `PLAN.md`, `TASKS.md`, and `protocol/PROTOCOL.md`
- keep runtime code understandable; do not spread core state transitions across too many files