relaybrain 0.0.0-stage → 0.2.1

package/cli/relay.js

@@ -0,0 +1,475 @@
+#!/usr/bin/env node
+const fs = require("fs");
+const path = require("path");
+const { spawn, spawnSync } = require("child_process");
+
+const root = path.join(__dirname, "..");
+const cmd = process.argv[2] || "help";
+const rest = process.argv.slice(3);
+
+function help() {
+  console.log(`Relay — GitHub Desktop for AI agents
+
+  relay login              Sign in with GitHub (uses gh CLI, or device flow if GITHUB_CLIENT_ID is set)
+  relay logout             Clear the local session
+  relay whoami             Show the signed-in GitHub user
+  relay clone <url> [dir]  git clone + register workspace + install agent hooks
+  relay add <path>         Attach an existing local repo
+  relay init [path]        Wire hooks, MCP, and relay-os instructions (default: cwd)
+  relay serve              Start the API and Mission Control on 127.0.0.1:3001 (prebuilt UI, fast start)
+  relay serve --no-ui      Start API + coordinator only
+  relay serve --dev        Run Mission Control with next dev on :3002 (hot reload, slow first load)
+  relay push               Send your dirty working-tree files to the shared room
+  relay pull               Apply the host's current dirty files onto this clone
+  relay status             Health check
+  relay mcp-url            Print the MCP config for this room's shared context endpoint
+  relay doctor             Why the Coordinator board is empty (run it on the machine that sees nothing)
+  relay graph <cmd>        Memory graph (FalkorDB): up | enable [url] | disable | status | stats | rebuild [id|all]
+`);
+}
+
+function killTree(child) {
+  if (!child?.pid) return;
+  try {
+    if (process.platform === "win32") {
+      spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"], {
+        stdio: "ignore",
+        windowsHide: true,
+        shell: false,
+      });
+    } else {
+      child.kill("SIGTERM");
+    }
+  } catch {
+    /* already gone */
+  }
+}
+
+function apiPort(args) {
+  const idx = args.indexOf("--port");
+  if (idx >= 0) return Number(args[idx + 1]);
+  return Number(process.env.RELAY_PORT || 3001);
+}
+
+async function waitForApi(url, ms = 30000) {
+  const start = Date.now();
+  while (Date.now() - start < ms) {
+    try {
+      const r = await fetch(url);
+      if (r.ok) return true;
+    } catch {
+      /* still booting */
+    }
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+  return false;
+}
+
+function newestMtime(dir) {
+  let newest = 0;
+  let entries = [];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) newest = Math.max(newest, newestMtime(full));
+    else newest = Math.max(newest, fs.statSync(full).mtimeMs);
+  }
+  return newest;
+}
+
+/** True when there is no prebuilt UI, or the UI source changed after it was built. */
+function staticUiStale() {
+  const ui = path.join(root, "mission-control");
+  const index = path.join(ui, "out", "index.html");
+  if (!fs.existsSync(index)) return true;
+  const builtAt = fs.statSync(index).mtimeMs;
+  const sources = ["app", "components", "lib", "styles", "public"].map((d) => newestMtime(path.join(ui, d)));
+  for (const f of ["next.config.js", "package.json"]) {
+    try {
+      sources.push(fs.statSync(path.join(ui, f)).mtimeMs);
+    } catch {
+      /* optional */
+    }
+  }
+  return Math.max(...sources) > builtAt;
+}
+
+/** Old bookmarks, docs and invite links point at :3002 — send them to the real UI. */
+function redirectOldUiPort(uiPort, uiOrigin) {
+  const http = require("http");
+  const server = http.createServer((req, res) => {
+    res.writeHead(302, { Location: `${uiOrigin}${req.url || "/"}` });
+    res.end();
+  });
+  server.on("error", () => {
+    /* port busy — nothing to redirect */
+  });
+  server.listen(Number(uiPort), "127.0.0.1");
+  server.unref();
+}
+
+async function serve(args) {
+  const noUi = args.includes("--no-ui");
+  const dev = args.includes("--dev");
+  const forwarded = args.filter((a) => !["--no-ui", "--static", "--dev"].includes(a));
+  const uiPort = process.env.RELAY_UI_PORT || "3002";
+  const port = apiPort(forwarded);
+  const apiOrigin = `http://127.0.0.1:${port}`;
+  const children = [];
+  // Mission Control is served prebuilt (mission-control/out) from the API port:
+  // `next dev` compiles the whole UI on first page load, which is a long blank
+  // wait. An npm install ships the build; a source checkout rebuilds it only when
+  // the UI source is newer. `--dev` keeps hot reload for working on the UI.
+  const nextBin = path.join(root, "node_modules", "next", "dist", "bin", "next");
+  if (!noUi && !dev && fs.existsSync(nextBin) && staticUiStale()) {
+    console.log("[relay] building Mission Control (once, after UI changes)…");
+    const built = spawnSync(process.execPath, [path.join(root, "scripts", "build-ui.js")], { stdio: "inherit", cwd: root });
+    if (built.status !== 0) console.error("[relay] UI build failed — falling back to `next dev`");
+  }
+  const hasStaticUi = fs.existsSync(path.join(root, "mission-control", "out", "index.html"));
+  const staticUi = !noUi && !dev && hasStaticUi;
+  const uiOrigin = staticUi ? `http://localhost:${port}` : `http://localhost:${uiPort}`;
+
+  const api = spawn(process.execPath, [path.join(root, "backend", "server.js"), ...forwarded], {
+    stdio: "inherit",
+    cwd: root,
+    windowsHide: false,
+    shell: false,
+    env: {
+      ...process.env,
+      RELAY_PORT: String(port),
+      RELAY_UI_ORIGIN: process.env.RELAY_UI_ORIGIN || uiOrigin,
+    },
+  });
+  children.push(api);
+
+  let shuttingDown = false;
+  function shutdown(code = 0) {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    for (const child of children) killTree(child);
+    process.exit(code);
+  }
+  process.on("SIGINT", () => shutdown(0));
+  process.on("SIGTERM", () => shutdown(0));
+  api.on("exit", (code) => {
+    if (!shuttingDown) shutdown(code || 0);
+  });
+
+  if (staticUi) {
+    redirectOldUiPort(uiPort, uiOrigin);
+    if (await waitForApi(`${apiOrigin}/api/health`)) console.log(`[relay] Mission Control → ${uiOrigin}`);
+  } else if (!noUi) {
+    if (!fs.existsSync(nextBin)) {
+      console.error("Mission Control is not installed — run npm install");
+      shutdown(1);
+      return;
+    }
+    const ready = await waitForApi(`${apiOrigin}/api/health`);
+    if (!ready) {
+      console.error("[relay] API did not become ready on", apiOrigin);
+      shutdown(1);
+      return;
+    }
+    const ui = spawn(process.execPath, [nextBin, "dev", "--port", String(uiPort)], {
+      stdio: "inherit",
+      cwd: path.join(root, "mission-control"),
+      windowsHide: false,
+      shell: false,
+      env: {
+        ...process.env,
+        NEXT_PUBLIC_RELAY_API: apiOrigin,
+      },
+    });
+    children.push(ui);
+    ui.on("exit", (code) => {
+      if (!shuttingDown) shutdown(code || 0);
+    });
+  }
+}
+
+/**
+ * Walks the exact chain the Coordinator board depends on and says which link is
+ * broken. Locks and the board are different subsystems — a hook claims straight
+ * against the host over HTTP, while the board is fed by the lock mirror and SSE
+ * — so "locking works but I see nothing" is a normal, and otherwise invisible,
+ * way for this to fail.
+ */
+async function doctor() {
+  const api = `http://127.0.0.1:${apiPort(rest)}`;
+  const ok = (m) => console.log(`  ok    ${m}`);
+  const bad = (m) => console.log(`  BROKE ${m}`);
+  const info = (m) => console.log(`        ${m}`);
+
+  console.log("relay doctor — room + Coordinator board\n");
+  let hostLockCount = 0;
+
+  let health;
+  try {
+    health = await fetch(`${api}/api/health`).then((r) => r.json());
+    ok(`local API on ${api}`);
+  } catch {
+    bad(`no local API on ${api} — run \`relay serve\` here`);
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const g = await fetch(`${api}/api/graph/health`).then((r) => r.json());
+    if (!g.running) info("memory graph off — `relay graph up && relay graph enable` to turn it on");
+    else if (g.breaker?.state === "closed") ok(`memory graph connected (${g.url})`);
+    else bad(`memory graph cannot reach FalkorDB at ${g.url}${g.breaker?.lastError ? ` (${g.breaker.lastError})` : ""} — \`relay graph status\``);
+  } catch {
+    info("memory graph status unavailable (older relay serve?)");
+  }
+
+  const room = health.room;
+  if (!room?.url) {
+    info("no room joined on this machine — the board shows only local agents.");
+    info("Host: Team tab -> Invite next to a teammate. Guest: Join on the Team tab.");
+    return;
+  }
+  ok(`room joined as ${room.role} -> ${room.url}`);
+  if (room.role === "host") {
+    info(`sharing ${room.hostProjectName || "?"} (${room.hostWorkspacePath || "?"})`);
+    info("A host reads its own lock table, so the board is local by definition.");
+  }
+
+  if (room.role === "guest") {
+    if (!room.hostProjectId) {
+      bad("room.json has no hostProjectId — the lock mirror never starts, so the");
+      info("board stays empty even while your locks work. Re-join with the invite link.");
+    } else {
+      ok(`mirroring host project ${room.hostProjectId}`);
+    }
+    const token = require("../backend/lib/room").loadRoom()?.memberToken;
+    const hit = async (p) => {
+      const r = await fetch(`${String(room.url).replace(/\/$/, "")}${p}`, {
+        headers: {
+          "ngrok-skip-browser-warning": "relay",
+          ...(token ? { "x-relay-room-token": token } : {}),
+        },
+        signal: AbortSignal.timeout(6000),
+      });
+      if (!r.ok) throw new Error(`${r.status}`);
+      return r.json();
+    };
+    try {
+      await hit("/api/health");
+      ok("host answers through the tunnel");
+    } catch (err) {
+      bad(`cannot reach the host (${err.message}) — board falls back to local locks`);
+      info("Host is unreachable — Relay will look up their current tunnel and reconnect.");
+    }
+    try {
+      const remote = await hit(`/api/locks?projectId=${encodeURIComponent(room.hostProjectId || "")}`);
+      hostLockCount = (remote.locks || []).length;
+      ok(`host reports ${hostLockCount} lock(s) for the shared project`);
+    } catch (err) {
+      bad(`host refused /api/locks (${err.message})` + (token ? "" : " — no member token stored"));
+    }
+  }
+
+  // The mirror polls on its own clock, so a lock claimed a moment ago has not
+  // necessarily landed yet. Give it a few beats before calling anything broken.
+  let mine = await fetch(`${api}/api/locks`).then((r) => r.json());
+  for (let i = 0; i < 8 && hostLockCount > 0 && !(mine.locks || []).length; i += 1) {
+    await new Promise((r) => setTimeout(r, 500));
+    mine = await fetch(`${api}/api/locks`).then((r) => r.json());
+  }
+  if (hostLockCount > 0 && !(mine.locks || []).length) {
+    bad("the host holds locks but this machine mirrors none of them.");
+    info("Locks still arbitrate correctly (hooks call the host directly); it is only");
+    info("the board that is fed by the mirror. Restart `relay serve` here — and if it");
+    info("comes back, report it: the mirror is not committing its polls.");
+  }
+
+  const localKeys = new Set(Object.values(mine.raw?.locks || {}).map((l) => `${l.filePath}::${l.agentId}`));
+  const fromHost = (mine.locks || []).filter((l) => !localKeys.has(`${l.filePath}::${l.agentId}`));
+  console.log("");
+  console.log(`  board would render ${(mine.locks || []).length} lock(s):`);
+  info(`${fromHost.length} mirrored from the room, ${localKeys.size} claimed on this machine`);
+  for (const l of mine.locks || []) {
+    info(`${l.filePath}  ${l.holder?.login ? "@" + l.holder.login : l.agentId}  ${l.mode || "write"}`);
+  }
+  if (!(mine.locks || []).length) {
+    console.log("");
+    info("Nothing is locked anywhere right now — an empty board here is correct.");
+    info("Have someone start an agent edit, then run this again.");
+  }
+}
+
+async function main() {
+  if (cmd === "help" || cmd === "-h" || cmd === "--help") {
+    help();
+    return;
+  }
+  if (cmd === "doctor") {
+    await doctor();
+    return;
+  }
+  if (cmd === "graph") {
+    await require("./graph").graph(rest);
+    return;
+  }
+  if (cmd === "serve") {
+    await serve(rest);
+    return;
+  }
+  if (cmd === "push" || cmd === "pull") {
+    try {
+      const r = await fetch(`http://127.0.0.1:3001/api/${cmd}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: "{}",
+      });
+      const body = await r.json();
+      if (!r.ok) {
+        console.error(body.hint || body.error || `${cmd} failed`);
+        process.exitCode = 1;
+        return;
+      }
+      const files = body.files || [];
+      console.log(files.length ? `${cmd} ${files.length} file(s)` : `${cmd}: nothing to ${cmd}`);
+      for (const file of files) console.log(`  ${file}`);
+    } catch {
+      console.error("offline — run relay serve");
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (cmd === "status") {
+    try {
+      const r = await fetch("http://127.0.0.1:3001/api/health");
+      console.log(JSON.stringify(await r.json(), null, 2));
+    } catch {
+      console.error("offline — run relay serve");
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  const gh = require("../backend/lib/githubLogin");
+  const clone = require("../backend/lib/cloneRepo");
+
+  if (cmd === "whoami") {
+    const { user, session } = gh.whoami();
+    if (!user) {
+      console.log("not signed in — run relay login");
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`${user.name} (@${user.login})`);
+    if (session.projectId) console.log(`project ${session.projectId}`);
+    return;
+  }
+
+  if (cmd === "logout") {
+    gh.logout();
+    console.log("signed out");
+    return;
+  }
+
+  if (cmd === "login") {
+    try {
+      const user = await gh.loginFromGh();
+      console.log(`signed in as ${user.name} (@${user.login}) via GitHub CLI`);
+      return;
+    } catch (err) {
+      if (process.env.GITHUB_CLIENT_ID) {
+        const device = await gh.loginDeviceFlow();
+        console.log(`Open ${device.verification_uri} and enter code: ${device.user_code}`);
+        const user = await gh.pollDevice(device);
+        console.log(`signed in as ${user.name} (@${user.login})`);
+        return;
+      }
+      console.error(err.message || err);
+      console.error("Install GitHub CLI and run: gh auth login");
+      console.error("Or set GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET and use Mission Control → Continue with GitHub.");
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (cmd === "clone") {
+    const url = rest[0];
+    const dir = rest[1];
+    const { project, path: dest } = await clone.cloneRepo(url, dir);
+    console.log(`cloned ${url}`);
+    console.log(`workspace ${dest}`);
+    console.log(`registered ${project.name} (${project.id})`);
+    return;
+  }
+
+  if (cmd === "add") {
+    const project = clone.addLocal(rest[0], rest[1]);
+    console.log(`added ${project.path} as ${project.name}`);
+    return;
+  }
+
+  if (cmd === "init") {
+    const target = path.resolve(rest[0] || process.cwd());
+    if (!fs.existsSync(target)) {
+      console.error(`path not found: ${target}`);
+      process.exitCode = 1;
+      return;
+    }
+    const { installProjectHooks, installGlobalHooks } = require("../backend/lib/installHooks");
+    try {
+      installProjectHooks(target);
+      installGlobalHooks();
+      const existing = clone.addLocal(target, path.basename(target));
+      console.log(`Relay initialized in ${existing.path}`);
+      console.log("Hooks + MCP wired for Cursor, Claude Code, Codex, Copilot CLI, Antigravity.");
+      console.log("Run `relay serve`, then say `/relay ask` in any agent — it calls MCP relay_room_brief.");
+    } catch (err) {
+      console.error(err.message || err);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (cmd === "mcp-url") {
+    const room = require("../backend/lib/room").loadRoom();
+    if (!room?.url) {
+      console.log("Not in a room. `relay serve`, then Share in Mission Control, or join with an invite link.");
+      console.log("Locally your agents already reach relay over stdio — nothing to configure.");
+      process.exitCode = 1;
+      return;
+    }
+    const config = {
+      mcpServers: {
+        "relay-room": {
+          type: "http",
+          url: `${String(room.url).replace(/\/$/, "")}/mcp`,
+          headers: {
+            "ngrok-skip-browser-warning": "relay",
+            ...(room.memberToken ? { "x-relay-room-token": room.memberToken } : {}),
+          },
+        },
+      },
+    };
+    console.log(`Room MCP endpoint (${room.role}) — read-only for anyone off this machine.\n`);
+    console.log(JSON.stringify(config, null, 2));
+    console.log(`\nPaste into the agent's MCP config. It exposes the room's context (chat history,
+recent edits, locks, conflicts) to any MCP client — including one on a machine
+with no relay installed. Locks and other writes stay on each member's own relay.`);
+    if (!room.memberToken && room.role === "guest") {
+      console.log("\nNo member token on file — if the host made the room invite-only, re-join with the invite link.");
+    }
+    return;
+  }
+
+  help();
+  process.exitCode = 1;
+}
+
+main().catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/docker-compose.falkor.yml

@@ -0,0 +1,17 @@
+services:
+  falkordb:
+    image: falkordb/falkordb:latest
+    container_name: relay-falkordb
+    ports:
+      - "6379:6379"
+      - "3010:3000"
+    environment:
+      # RDB snapshots, not AOF: replaying FalkorDB's AOF effect stream can segfault
+      # on restart (see #21). Relay re-sends anything a lost snapshot missed.
+      REDIS_ARGS: "--save 30 1 --save 300 10 --appendonly no"
+    volumes:
+      # The image writes here; /data only holds a symlink, so mounting /data persisted nothing.
+      - falkordb_data:/var/lib/falkordb/data
+    restart: unless-stopped
+volumes:
+  falkordb_data: {}