add scaffold plan
This commit is contained in:
249
SCAFFOLD.md
Normal file
249
SCAFFOLD.md
Normal file
@@ -0,0 +1,249 @@
|
|||||||
|
# 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.
|
||||||
Reference in New Issue
Block a user