@mrrlin-dev/mcp 0.2.6 → 0.3.1

package/README.md

@@ -0,0 +1,81 @@
+# `@mrrlin-dev/mcp` — Mrrlin Director Bridge
+
+CLI that runs the local Director bridge under PM2 and forwards chat turns to a locally-spawned Codex `app-server`. Installed globally on operator boxes via `pnpm install -g @mrrlin-dev/mcp`.
+
+## Self-update & process hygiene
+
+The bridge auto-picks up new `@mrrlin-dev/mcp` versions after `pnpm install -g`. No manual `pm2 restart` is required.
+
+### How it works
+
+- **L1 (self-update loop):** every 15 minutes (env-tunable) the bridge hashes its own `bin.cjs` and, on change, drains the current Codex turn cleanly and exits via `bridgeShutdown`. PM2 restarts. New code loads.
+- **L2 (postinstall nudge):** `pnpm install -g @mrrlin-dev/mcp@latest` triggers a `SIGUSR2` to every running PM2 bridge, collapsing the L1 wait to seconds.
+- **L3 (in-chat update offer):** every 6 hours the bridge checks `https://registry.npmjs.org/@mrrlin-dev/mcp/latest`. When a newer version is published, on your next chat turn the Director asks: *"Бачу що bridge на X, на npm уже Y — оновити зараз?"*. Say "yes" → Director runs `pnpm install -g @mrrlin-dev/mcp@latest` itself. 48h cooldown if you decline.
+- **L4 (process hygiene):** the bridge refuses to start a second instance on the same port and warns about orphan `mrrlin-mcp director-bridge` processes at startup.
+
+### Env tuning
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `MRRLIN_DIRECTOR_BRIDGE_SELF_UPDATE` | (unset = on) | Set `0` to disable L1 (and silence L2 SIGUSR2 effect). |
+| `MRRLIN_DIRECTOR_BRIDGE_SELF_UPDATE_INTERVAL_MS` | `900000` (15 min) | L1 hash-check interval. |
+| `MRRLIN_DIRECTOR_BRIDGE_REGISTRY_POLL_INTERVAL_MS` | `21600000` (6 h) | L3.1 npm registry poll interval. |
+| `MRRLIN_DIRECTOR_BRIDGE_UPDATE_COOLDOWN_MS` | `172800000` (48 h) | L3.2 in-chat update-offer cooldown. |
+| `MRRLIN_MCP_POSTINSTALL_SKIP` | unset | Set `1` to skip the postinstall SIGUSR2 nudge. |
+| `CI` | unset | Set `1` to skip the postinstall nudge in CI. |
+
+### PM2 ecosystem (automatic via `mrrlin-mcp install-service`)
+
+`mrrlin-mcp install-service` writes `~/.mrrlin/ecosystem.config.cjs` automatically. The generated config already includes `kill_timeout: 10000` so the bridge has 10s to drain cleanly before PM2 SIGKILLs. Reference shape:
+
+```js
+module.exports = {
+  apps: [{
+    name: "mrrlin-bridge",
+    script: "mrrlin-mcp",
+    args: "director-bridge",
+    interpreter: "none",
+    cwd: "<repo cwd>",
+    autorestart: true,
+    max_restarts: 10,
+    restart_delay: 3000,
+    kill_timeout: 10000,
+    env: { /* ... */ },
+  }],
+};
+```
+
+### Verifying the self-update path is wired
+
+Tail the bridge logs after a fresh start:
+
+```sh
+pm2 logs mrrlin-bridge --lines 50 | grep "bridge.self_update.startup"
+```
+
+Expect a JSON-fielded line including `version`, `binSha`, `selfUpdateEnabled`, `intervalMs`. Any non-default tuning shows up here.
+
+### One-time cleanup for zombie processes
+
+If you see multiple `mrrlin-mcp director-bridge` processes accumulating (`pgrep -f "mrrlin-mcp director-bridge"` returns > 1 PID), run once:
+
+```sh
+pm2 stop mrrlin-bridge
+pkill -f "mrrlin-mcp director-bridge" || true
+sleep 2
+pm2 start ~/.mrrlin/ecosystem.config.cjs
+```
+
+This is only needed for the legacy population (bridges started before this self-update mechanism shipped). New installs won't produce zombies thanks to L1's `bridgeShutdown` exit path.
+
+### Update offer UX (L3) — what the operator sees
+
+When a newer `@mrrlin-dev/mcp` is published and your bridge polls (within 6h):
+
+1. On your next chat turn, the Director weaves a yes/no question in: *"Бачу що bridge на X, на npm уже Y — оновити зараз? (запущу `pnpm install -g @mrrlin-dev/mcp@latest`)"*
+2. You reply "yes" / "так" / "ага" → Director runs the install via its shell tool, reports stdout + exit code in chat.
+3. L1 picks up the new `bin.cjs` (or L2 SIGUSR2 nudges it sooner) → drain-on-quiet → PM2 restart → web reconnects.
+4. You reply "later" → Director acknowledges and drops it for 48h.
+5. If the install fails (sudo, registry pin, network) → Director shows the error verbatim plus the manual command.
+
+The Director **never installs without explicit confirmation**.