Yonexus.Server/SCAFFOLD.md

Yonexus.Server — Scaffold Plan

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

1. Planned Tree

.
├── plugin/
│   ├── core/
│   │   ├── registry.ts
│   │   ├── pairing.ts
│   │   ├── auth.ts
│   │   ├── heartbeat.ts
│   │   ├── dispatch.ts
│   │   └── errors.ts
│   ├── hooks/
│   │   ├── onGatewayStart.ts
│   │   └── onGatewayStop.ts
│   ├── commands/
│   │   ├── listClients.ts
│   │   ├── showClient.ts
│   │   └── rePairClient.ts
│   ├── tools/
│   │   ├── sendMessageToClient.ts
│   │   ├── listClientStatus.ts
│   │   └── getPairingState.ts
│   ├── index.ts
│   └── openclaw.plugin.json
├── skills/
│   └── ...
├── servers/
│   ├── wsServer.ts
│   └── sessionManager.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 server core modules
• import hooks
• import commands
• import tools
• initialize server runtime container
• register hooks with OpenClaw
• register commands with OpenClaw
• register tools with OpenClaw

Design rule:

• no pairing/auth/dispatch business logic should live directly in this file

---

3. plugin/openclaw.plugin.json

Planned manifest responsibilities:

• define plugin name: Yonexus.Server
• define entrypoint
• declare version
• define config schema / default config shape
• declare plugin metadata
• declare permissions if needed

Planned Config Shape

{
  "followerIdentifiers": [],
  "notifyBotToken": "",
  "adminUserId": "",
  "listenHost": "0.0.0.0",
  "listenPort": 8787,
  "publicWsUrl": ""
}

Planned Validation Expectations

• listenPort must be required
• followerIdentifiers must be an array
• notifyBotToken must be required
• adminUserId must be required

---

4. plugin/core/

registry.ts

Planned responsibilities:

• client registry CRUD
• active session tracking
• persistent state load/save

pairing.ts

Planned responsibilities:

• pairing code generation
• pairing pending state
• Discord DM notification orchestration
• pair_confirm validation
• secret issuance

auth.ts

Planned responsibilities:

• auth_request verification
• signature verification
• nonce window validation
• rate-limit checks
• re-pair trigger decisions

heartbeat.ts

Planned responsibilities:

• lastHeartbeatAt updates
• status transitions
• sweep timer logic
• disconnect timeout handling

dispatch.ts

Planned responsibilities:

• builtin message routing
• application rule rewriting
• rule registry
• rule dispatch
• sendMessageToClient routing

errors.ts

Planned responsibilities:

• typed/structured error definitions
• standard server-side error codes

---

5. plugin/hooks/

onGatewayStart.ts

Planned responsibilities:

• initialize registry/runtime
• start WebSocket server
• start heartbeat sweep

onGatewayStop.ts

Planned responsibilities:

• stop heartbeat sweep
• close sockets gracefully
• persist final state if needed

---

6. plugin/commands/

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

Potential first commands:

• listClients.ts — list known clients and statuses
• showClient.ts — inspect one client’s trust/liveness state
• rePairClient.ts — revoke trust and force next reconnect to re-pair

---

7. plugin/tools/

Potential first tools:

• sendMessageToClient.ts
• listClientStatus.ts
• getPairingState.ts

These should wrap core logic, not duplicate it.

---

8. servers/

wsServer.ts

Planned responsibilities:

• WebSocket server startup and bind
• connection accept lifecycle
• socket-level send/receive plumbing

sessionManager.ts

Planned responsibilities:

• map identifiers to active connections
• enforce one active session per identifier
• close/replace older sessions when needed

Design rule:

• service bootstrap/network transport code belongs here
• reusable business/state logic stays in plugin/core/

---

9. skills/

Initial version may keep this minimal.

Possible future skill topics:

• Yonexus.Server operations
• pairing recovery
• debugging auth failures

---

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 server plugin config if explicitly desired later

---

11. Initial Bring-Up Order

Recommended first implementation order:

1. manifest + plugin/index.ts
2. servers/wsServer.ts
3. plugin/core/registry.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.
• Commands and tools can start thin and grow later.