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