add scaffold plan
This commit is contained in:
242
SCAFFOLD.md
Normal file
242
SCAFFOLD.md
Normal file
@@ -0,0 +1,242 @@
|
||||
# Yonexus.Client — Scaffold Plan
|
||||
|
||||
This document refines the repository structure into concrete planned files and responsibilities.
|
||||
|
||||
## 1. Planned Tree
|
||||
|
||||
```text
|
||||
.
|
||||
├── 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
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
Reference in New Issue
Block a user