250 lines
5.4 KiB
Markdown
250 lines
5.4 KiB
Markdown
# Yonexus.Server — Scaffold Plan
|
||
|
||
This document refines the repository structure into concrete planned files and responsibilities.
|
||
|
||
## 1. Planned Tree
|
||
|
||
```text
|
||
.
|
||
├── 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
|
||
|
||
```json
|
||
{
|
||
"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.
|