# Yonexus.Client — Scaffold Plan

This document refines the repository structure into concrete planned files and responsibilities.

## 1. Planned Tree

```text
.
├── plugin/
│   ├── core/
│   │   ├── localState.ts
│   │   ├── keys.ts
│   │   ├── pairing.ts
│   │   ├── auth.ts
│   │   ├── heartbeat.ts
│   │   ├── dispatch.ts
│   │   └── errors.ts
│   ├── hooks/
│   │   ├── onGatewayStart.ts
│   │   └── onGatewayStop.ts
│   ├── commands/
│   │   ├── showStatus.ts
│   │   ├── reconnect.ts
│   │   └── resetTrust.ts
│   ├── tools/
│   │   ├── sendMessageToServer.ts
│   │   └── getConnectionState.ts
│   ├── index.ts
│   └── openclaw.plugin.json
├── skills/
│   └── ...
├── servers/
│   └── clientRuntime.ts
├── scripts/
│   └── install.mjs
├── protocol/
│   └── ... (submodule)
├── PLAN.md
├── STRUCTURE.md
└── SCAFFOLD.md
```

This is a planning scaffold, not yet an implementation commitment down to exact filenames. Names may evolve, but responsibilities should remain stable.

---

## 2. `plugin/index.ts`

`plugin/index.ts` is wiring only.

Planned responsibilities:
- import client core modules
- import hooks
- import commands
- import tools
- initialize client runtime container
- register hooks with OpenClaw
- register commands with OpenClaw
- register tools with OpenClaw

Design rule:
- no reconnect/auth/pairing business logic should live directly in this file

---

## 3. `plugin/openclaw.plugin.json`

Planned manifest responsibilities:
- define plugin name: `Yonexus.Client`
- define entrypoint
- declare version
- define config schema / default config shape
- declare plugin metadata
- declare permissions if needed

### Planned Config Shape

```json
{
  "mainHost": "",
  "identifier": "",
  "notifyBotToken": "",
  "adminUserId": ""
}
```

### Planned Validation Expectations

- `mainHost` must be required
- `identifier` must be required
- `mainHost` should be a valid WebSocket endpoint

---

## 4. `plugin/core/`

### `localState.ts`
Planned responsibilities:
- load/save client local trust state
- persist secret and timestamps
- manage current pairing/auth state

### `keys.ts`
Planned responsibilities:
- generate Ed25519 keypair
- load/save encoded keys
- sign auth proof payloads

### `pairing.ts`
Planned responsibilities:
- track pending pairing flow
- accept human-provided pairing code
- send pair_confirm
- store secret after pair_success

### `auth.ts`
Planned responsibilities:
- construct proof payload
- create signature
- send auth_request
- handle auth_success/auth_failed
- react to re_pair_required

### `heartbeat.ts`
Planned responsibilities:
- schedule heartbeat loop
- stop loop on disconnect
- handle optional heartbeat_ack

### `dispatch.ts`
Planned responsibilities:
- builtin message routing
- application rule registry
- inbound message dispatch
- sendMessageToServer routing

### `errors.ts`
Planned responsibilities:
- typed/structured error definitions
- standard client-side error codes

---

## 5. `plugin/hooks/`

### `onGatewayStart.ts`
Planned responsibilities:
- initialize local state
- ensure keypair exists
- start client runtime
- attempt initial connection

### `onGatewayStop.ts`
Planned responsibilities:
- stop heartbeat
- close socket gracefully
- persist final state if needed

---

## 6. `plugin/commands/`

These are optional in early versions, but the directory should exist.

Potential first commands:
- `showStatus.ts` — inspect connection/auth/pairing status
- `reconnect.ts` — manually trigger reconnect
- `resetTrust.ts` — clear local secret and force re-pair

---

## 7. `plugin/tools/`

Potential first tools:
- `sendMessageToServer.ts`
- `getConnectionState.ts`

These should wrap core logic, not duplicate it.

---

## 8. `servers/`

### `clientRuntime.ts`
Planned responsibilities:
- manage WebSocket client runtime
- manage reconnect/backoff loop
- broker raw send/receive with server

Design rule:
- even though the client is not primarily a server, runtime/service bootstrap code still belongs in `servers/` for structural consistency
- reusable logic remains in `plugin/core/`

---

## 9. `skills/`

Initial version may keep this minimal.

Possible future skill topics:
- reconnect troubleshooting
- pairing recovery
- auth debugging guidance

---

## 10. `scripts/install.mjs`

Planned CLI responsibilities:
- `--install`
- `--uninstall`
- `--openclaw-profile-path <path>`

Planned install behavior:
- build output copied into the OpenClaw plugin directory
- install target path determined by profile path

Planned uninstall behavior:
- remove installed plugin directory
- optionally clean local client config if explicitly desired later

---

## 11. Initial Bring-Up Order

Recommended first implementation order:
1. manifest + `plugin/index.ts`
2. `servers/clientRuntime.ts`
3. `plugin/core/localState.ts`
4. hello / hello_ack routing
5. pairing flow
6. auth flow
7. heartbeat
8. commands/tools

---

## 12. Notes

- `protocol/` is the single protocol source of truth; do not duplicate protocol docs in this repo.
- File names can change, but the wiring/core/service separation should remain.
- `servers/` should exist even if early client runtime is lightweight.