Yonexus.Client/SCAFFOLD.md

Yonexus.Client — Scaffold Plan

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

1. Planned Tree

.
├── 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

{
  "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.