diff --git a/SYNC_GUIDE.md b/SYNC_GUIDE.md new file mode 100644 index 0000000..dad511e --- /dev/null +++ b/SYNC_GUIDE.md @@ -0,0 +1,36 @@ +# KoalaSync Protocol Synchronization Guide (SYNC_GUIDE.md) + +## Why do we need to sync? +KoalaSync uses a "Single Source of Truth" for its communication protocol constants located in the `shared/` directory. However, Chrome Extensions (Manifest V3) are strictly sandboxed and **cannot load or import files from outside their root directory**. + +To ensure that the extension and the relay server are always using the exact same event names and protocol versions, we must maintain a mirrored copy of the shared files within the extension folder. + +## When should you run the sync script? +You MUST run the synchronization script in any of the following scenarios: +1. **After modifying** `shared/constants.js`. +2. **After modifying** `shared/blacklist.js`. +3. **Before committing** changes to the repository if any protocol-related files were touched. +4. **Before deploying** the server or releasing the extension. + +## How to sync + +### On Windows +Run the batch script from the repository root: +```powershell +.\scripts\sync-constants.bat +``` + +### On macOS / Linux +Run the shell script from the repository root: +```bash +./scripts/sync-constants.sh +``` + +## What does it do? +The script performs the following actions: +1. Ensures the `extension/shared/` directory exists. +2. Copies `shared/constants.js` to `extension/shared/constants.js`. +3. Copies `shared/blacklist.js` to `extension/shared/blacklist.js`. + +> [!CAUTION] +> **NEVER** edit the files inside `extension/shared/` directly. They will be overwritten the next time the sync script is run. Always edit the files in the root `shared/` directory and then run the sync script.