Yonexus.Server/MANIFEST.md

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:

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:

{
  "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:

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:

${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