add manifest and install plan
This commit is contained in:
228
MANIFEST.md
Normal file
228
MANIFEST.md
Normal file
@@ -0,0 +1,228 @@
|
||||
# Yonexus.Server — Manifest & Install Plan
|
||||
|
||||
This document refines the planned plugin manifest and install script behavior for `Yonexus.Server`.
|
||||
|
||||
## 1. Manifest File Location
|
||||
|
||||
Required file:
|
||||
|
||||
```text
|
||||
plugin/openclaw.plugin.json
|
||||
```
|
||||
|
||||
This file is the OpenClaw plugin manifest and must be treated as the single manifest entrypoint for this repository.
|
||||
|
||||
---
|
||||
|
||||
## 2. Planned Manifest Responsibilities
|
||||
|
||||
The manifest should define at minimum:
|
||||
- plugin name
|
||||
- plugin version
|
||||
- plugin description
|
||||
- plugin entrypoint
|
||||
- default config shape
|
||||
- config validation expectations
|
||||
- permissions if required by runtime integration
|
||||
|
||||
---
|
||||
|
||||
## 3. Planned Manifest Skeleton
|
||||
|
||||
Initial planning shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Yonexus.Server",
|
||||
"version": "0.1.0",
|
||||
"description": "Yonexus central hub plugin for cross-instance OpenClaw communication",
|
||||
"entry": "dist/plugin/index.js",
|
||||
"permissions": [],
|
||||
"config": {
|
||||
"followerIdentifiers": [],
|
||||
"notifyBotToken": "",
|
||||
"adminUserId": "",
|
||||
"listenHost": "0.0.0.0",
|
||||
"listenPort": 8787,
|
||||
"publicWsUrl": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This is not yet final schema syntax; it is the planned manifest contract.
|
||||
|
||||
---
|
||||
|
||||
## 4. Field-Level Intent
|
||||
|
||||
### `name`
|
||||
Must be:
|
||||
- `Yonexus.Server`
|
||||
|
||||
### `version`
|
||||
Initial planned value:
|
||||
- `0.1.0`
|
||||
|
||||
### `description`
|
||||
Should make clear this is the hub/server-side Yonexus plugin.
|
||||
|
||||
### `entry`
|
||||
Expected build target:
|
||||
- `dist/plugin/index.js`
|
||||
|
||||
This assumes build output mirrors the plugin source tree under `dist/`.
|
||||
|
||||
### `permissions`
|
||||
Initial expected value:
|
||||
- empty or minimal until implementation proves extra permissions are needed
|
||||
|
||||
Potential future needs may include:
|
||||
- messaging capability for Discord DM via bot token path if exposed through runtime integration
|
||||
- filesystem access depending on plugin runtime packaging expectations
|
||||
|
||||
### `config`
|
||||
Server-specific config block.
|
||||
|
||||
---
|
||||
|
||||
## 5. Server Config Field Semantics
|
||||
|
||||
### `followerIdentifiers: string[]`
|
||||
Allowlist of client identifiers permitted to pair/connect.
|
||||
|
||||
Validation expectations:
|
||||
- required
|
||||
- must be an array
|
||||
- values should be non-empty strings
|
||||
- duplicates should be rejected or normalized away
|
||||
|
||||
### `notifyBotToken: string`
|
||||
Discord bot token used by the server to send pairing DM notifications.
|
||||
|
||||
Validation expectations:
|
||||
- required
|
||||
- non-empty string
|
||||
- treated as secret/sensitive config
|
||||
- never logged in plaintext
|
||||
|
||||
### `adminUserId: string`
|
||||
Discord user id of the human administrator who receives pairing DMs.
|
||||
|
||||
Validation expectations:
|
||||
- required
|
||||
- non-empty string
|
||||
- ideally numeric-string format validation if that is reliable for Discord usage
|
||||
|
||||
### `listenHost: string`
|
||||
Local bind host for the WebSocket server.
|
||||
|
||||
Validation expectations:
|
||||
- optional with default `0.0.0.0`
|
||||
- must be valid host/bind string
|
||||
|
||||
### `listenPort: number`
|
||||
Local bind port for the WebSocket server.
|
||||
|
||||
Validation expectations:
|
||||
- required
|
||||
- integer
|
||||
- valid TCP port range
|
||||
|
||||
### `publicWsUrl: string`
|
||||
Optional canonical external WebSocket URL used for documentation/operator reference.
|
||||
|
||||
Validation expectations:
|
||||
- optional
|
||||
- if provided, should be a valid `ws://` or `wss://` URL
|
||||
|
||||
---
|
||||
|
||||
## 6. Manifest Validation Policy
|
||||
|
||||
Initialization must fail when:
|
||||
- `followerIdentifiers` is missing or malformed
|
||||
- `notifyBotToken` is missing
|
||||
- `adminUserId` is missing
|
||||
- `listenPort` is missing or invalid
|
||||
|
||||
Initialization should warn or fail when:
|
||||
- `publicWsUrl` is provided but malformed
|
||||
- duplicate identifiers are present in `followerIdentifiers`
|
||||
|
||||
---
|
||||
|
||||
## 7. Install Script File Location
|
||||
|
||||
Required file:
|
||||
|
||||
```text
|
||||
scripts/install.mjs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Install Script Responsibilities
|
||||
|
||||
The install script should support:
|
||||
- `--install`
|
||||
- `--uninstall`
|
||||
- `--openclaw-profile-path <path>`
|
||||
|
||||
Default profile path:
|
||||
- `~/.openclaw`
|
||||
|
||||
### Install Behavior
|
||||
|
||||
When `--install` is used:
|
||||
- ensure build output exists
|
||||
- copy the built plugin into the OpenClaw plugins directory
|
||||
- target path should correspond to `Yonexus.Server`
|
||||
|
||||
Planned target form:
|
||||
|
||||
```text
|
||||
${openclawProfilePath}/plugins/Yonexus.Server
|
||||
```
|
||||
|
||||
### Uninstall Behavior
|
||||
|
||||
When `--uninstall` is used:
|
||||
- remove installed plugin files from the OpenClaw plugins directory
|
||||
- optionally preserve or separately handle runtime data/config unless explicit cleanup mode is added later
|
||||
|
||||
---
|
||||
|
||||
## 9. Install Script Design Notes
|
||||
|
||||
The install script should:
|
||||
- be idempotent where reasonable
|
||||
- fail clearly on missing build artifacts
|
||||
- not silently delete unrelated files
|
||||
- keep install/uninstall behavior explicit
|
||||
|
||||
Possible future options:
|
||||
- `--force`
|
||||
- `--clean-config`
|
||||
- `--print-target`
|
||||
|
||||
These are not required yet.
|
||||
|
||||
---
|
||||
|
||||
## 10. Expected Relationship to Build Output
|
||||
|
||||
Planned build assumption:
|
||||
- source lives under `plugin/`
|
||||
- compiled output lands under `dist/plugin/`
|
||||
- manifest entry points at compiled `dist/plugin/index.js`
|
||||
|
||||
The install script should copy only what is needed for runtime use.
|
||||
|
||||
---
|
||||
|
||||
## 11. Documentation Rule
|
||||
|
||||
When implementation begins:
|
||||
- `MANIFEST.md` should stay as planning/reference
|
||||
- `plugin/openclaw.plugin.json` becomes the executable truth
|
||||
- if the two ever diverge, the manifest must be updated and docs corrected quickly
|
||||
Reference in New Issue
Block a user