rexp-web 0.0.0-stage → 0.1.1

package/server/errors.mjs

@@ -0,0 +1,20 @@
+export function errorInfo(error) {
+  let details = error instanceof Error ? error.message : String(error);
+  try {
+    const parsed = JSON.parse(details);
+    if (typeof parsed.message === "string") details = parsed.message;
+  } catch { /* Ordinary non-JSON errors remain valid diagnostic details. */ }
+  let state = "error", message = "实验数据暂时无法读取，稍后会自动重试。";
+  if (/需要更新以支持按需读取/u.test(details)) {
+    message = '此节点的平台需要更新，才能按页读取参数搜索。';
+  } else if (/Unknown or disabled plugin: rexp|Missing plugin settings?: [^\n]*(?:platformRoot|rexpPath)/iu.test(details)) {
+    state = "unconfigured"; message = "此节点尚未配置实验平台。";
+  } else if (/(?:rexp(?:\.exe)?['"\s:].*(?:not recognized|not found|No such file)|(?:term|command).*rexp\.exe.*not recognized)|No module named ['"]?rexp/isu.test(details)) {
+    state = "not_installed"; message = "此节点的实验平台尚未安装完成，安装后会自动检测。";
+  } else if (/Platform not initialized|No platform root configured|未初始化/iu.test(details)) {
+    state = "not_initialized"; message = "此节点的实验平台尚未初始化，请确认数据根目录。";
+  } else if (/Connection closed|timed? out|ECONNRESET|ECONNREFUSED/iu.test(details)) {
+    message = "暂时无法连接此节点，正在等待恢复。";
+  }
+  return { state, message, details: details.slice(0, 6000) };
+}

package/server/run-monitor.mjs

@@ -0,0 +1,140 @@
+import fs from "node:fs";
+import path from "node:path";
+import { errorInfo } from "./errors.mjs";
+
+const alertStatuses = new Set(["COMPLETED", "FAILED", "RECOVERABLE"]);
+const maxEvents = 500;
+const maxEventAge = 24 * 60 * 60 * 1000;
+
+export class RunMonitor {
+  constructor({ listServers, readRuns, stateFile, intervalMs = 30_000 }) {
+    this.listServers = listServers;
+    this.readRuns = readRuns;
+    this.stateFile = stateFile;
+    this.intervalMs = intervalMs;
+    this.observed = {};
+    this.snapshots = new Map();
+    this.events = [];
+    this.sequence = 0;
+    this.listeners = new Set();
+    this.running = false;
+    this.stopped = true;
+    this.generation = 0;
+    this.lastCheckedAt = null;
+    this.lastError = null;
+    this.nodeErrors = {};
+    this.load();
+  }
+
+  load() {
+    try {
+      const saved = JSON.parse(fs.readFileSync(this.stateFile, "utf8"));
+      if (saved.version !== 1 || !saved.observed || typeof saved.observed !== "object") return;
+      this.observed = saved.observed;
+      this.sequence = Number.isSafeInteger(saved.sequence) ? saved.sequence : 0;
+      this.events = Array.isArray(saved.events) ? saved.events.filter((item) => item && Number.isSafeInteger(item.id) && Date.now() - Date.parse(item.at) < maxEventAge).slice(-maxEvents) : [];
+    } catch { /* An absent or invalid cache starts with a fresh baseline. */ }
+  }
+
+  save() {
+    fs.mkdirSync(path.dirname(this.stateFile), { recursive: true, mode: 0o700 });
+    const temp = `${this.stateFile}.${process.pid}.tmp`;
+    fs.writeFileSync(temp, JSON.stringify({ version: 1, observed: this.observed, sequence: this.sequence, events: this.events }), { mode: 0o600 });
+    fs.renameSync(temp, this.stateFile);
+  }
+
+  async tick() {
+    if (this.running || this.stopped) return;
+    const generation = this.generation;
+    clearTimeout(this.timer);
+    this.running = true;
+    this.lastError = null;
+    try {
+      const servers = await this.listServers();
+      const aliases = new Set(servers.map(server => server.alias));
+      for (const alias of Object.keys(this.nodeErrors)) if (!aliases.has(alias)) delete this.nodeErrors[alias];
+      for (const server of servers) {
+        if (this.stopped || generation !== this.generation) break;
+        if (server.state === "offline") continue;
+        try {
+          const snapshot = await this.readRuns(server.alias);
+          if (this.stopped || generation !== this.generation) break;
+          delete this.nodeErrors[server.alias];
+          this.snapshots.set(server.alias, snapshot);
+          if (!snapshot.available) {
+            delete this.observed[server.alias];
+            for (const listener of this.listeners) listener({ type: "runs", alias: server.alias, snapshot });
+            continue;
+          }
+          const previous = this.observed[server.alias];
+          const current = Object.fromEntries(snapshot.runs.map((run) => [run.id, run.status]));
+          this.observed[server.alias] = current;
+          this.snapshots.set(server.alias, snapshot);
+          if (previous) {
+            for (const run of snapshot.runs) {
+              if (!alertStatuses.has(run.status) || previous[run.id] === run.status) continue;
+              const event = {
+                id: ++this.sequence, at: new Date().toISOString(), alias: server.alias,
+                runId: run.id, project: run.project, version: run.version,
+                experiment: run.experiment, description: run.description?.trim() || undefined,
+                status: run.status, claimed: false,
+              };
+              this.events.push(event);
+              for (const listener of this.listeners) listener({ type: "transition", event });
+            }
+          }
+          for (const listener of this.listeners) listener({ type: "runs", alias: server.alias, snapshot });
+          this.events = this.events.filter((item) => Date.now() - Date.parse(item.at) < maxEventAge).slice(-maxEvents);
+          this.save();
+        } catch (error) {
+          this.nodeErrors[server.alias] = errorInfo(error);
+        }
+      }
+      this.lastCheckedAt = new Date().toISOString();
+    } catch (error) {
+      this.lastError = "无法更新节点列表，监测将自动重试。";
+    } finally {
+      this.running = false;
+      if (generation !== this.generation) {
+        if (!this.stopped) void this.tick();
+        return;
+      }
+      for (const listener of this.listeners) listener({ type: "monitor-status", status: this.status() });
+      if (!this.stopped) this.timer = setTimeout(() => { void this.tick(); }, this.intervalMs);
+    }
+  }
+
+  start() {
+    if (!this.stopped) return;
+    this.generation++;
+    this.stopped = false;
+    this.observed = {};
+    this.snapshots.clear();
+    this.lastCheckedAt = null;
+    this.lastError = null;
+    this.nodeErrors = {};
+    return this.tick();
+  }
+
+  stop() {
+    this.generation++;
+    this.stopped = true;
+    clearTimeout(this.timer);
+    this.snapshots.clear();
+    this.listeners.clear();
+  }
+
+  snapshot(alias) { return this.snapshots.get(alias); }
+  cursor() { return this.sequence; }
+  eventsAfter(cursor) { return this.events.filter((event) => event.id > cursor); }
+  subscribe(listener) { this.listeners.add(listener); return () => this.listeners.delete(listener); }
+  status() { return { monitoring: !this.stopped, intervalSeconds: this.intervalMs / 1000, lastCheckedAt: this.lastCheckedAt, lastError: this.lastError, nodeErrors: this.nodeErrors, cursor: this.sequence }; }
+
+  claim(id) {
+    const event = this.events.find((item) => item.id === id);
+    if (!event || event.claimed) return false;
+    event.claimed = true;
+    this.save();
+    return true;
+  }
+}

package/server/server-directory.mjs

@@ -0,0 +1,38 @@
+// Discover configured nodes without waiting for any SSH or platform probe.
+export function createServerDirectory({ invoke, now = Date.now, cacheMs = 1000, probeIntervalMs = 30_000 }) {
+  let snapshot;
+  let pending;
+  let probing;
+  let lastProbe = -Infinity;
+
+  function refreshStatus() {
+    if (probing || now() - lastProbe < probeIntervalMs) return;
+    lastProbe = now();
+    probing = Promise.resolve().then(() => invoke('list-servers', { refresh: true }, 45_000))
+      .then(() => { snapshot = undefined; })
+      .catch(() => { /* Node discovery still works when one status probe fails. */ })
+      .finally(() => { probing = undefined; });
+  }
+
+  return {
+    async list(force = false) {
+      if (!force && snapshot && now() - snapshot.at < cacheMs) return snapshot.items;
+      if (pending) return pending;
+      pending = (async () => {
+        const items = JSON.parse(await invoke('list-servers', { verbose: true }, 10_000));
+        if (!Array.isArray(items)) throw new Error('SSH-MCP 未返回服务器列表');
+        snapshot = { at: now(), items };
+        refreshStatus();
+        return items;
+      })();
+      try { return await pending; }
+      finally { pending = undefined; }
+    },
+    clear() { snapshot = undefined; },
+  };
+}
+
+export function serverState(item, busy) {
+  if (item.connected) return busy ? 'busy' : 'online';
+  return item.status?.reachable === false ? 'offline' : 'checking';
+}

package/server/web-paths.mjs

@@ -0,0 +1,21 @@
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+
+export function webPaths(home = process.env.REXP_WEB_HOME || os.homedir()) {
+  const configDir = path.join(home, '.config', 'rexp-hub');
+  const stateDir = path.join(home, '.cache', 'rexp-hub', 'web');
+  return {home, configDir, settingsFile:path.join(configDir,'web.json'), stateDir,
+    pidFile:path.join(stateDir,'service.json'), logFile:path.join(stateDir,'service.log')};
+}
+export function readWebSettings(paths = webPaths()) {
+  try {
+    const value = JSON.parse(fs.readFileSync(paths.settingsFile,'utf8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Expected an object');
+    return value;
+  } catch (error) { if (error.code === 'ENOENT') return {}; throw error; }
+}
+export function saveWebSettings(changes, paths = webPaths()) {
+  fs.mkdirSync(paths.configDir,{recursive:true,mode:0o700});
+  fs.writeFileSync(paths.settingsFile,JSON.stringify({...readWebSettings(paths),...changes},null,2)+'\n',{mode:0o600});
+}

package/server/web-service.mjs

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { closeBridge, handleApi } from "./bridge.mjs";
+import {webPaths} from "./web-paths.mjs";
+
+const projectDir = fileURLToPath(new URL("../", import.meta.url));
+const distDir = path.join(projectDir, "dist");
+const {stateDir,pidFile} = webPaths();
+const port = Number(process.env.REXP_WEB_PORT || 5173);
+const host = "127.0.0.1";
+const mime = { ".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8", ".css": "text/css; charset=utf-8", ".svg": "image/svg+xml", ".png": "image/png", ".ico": "image/x-icon", ".woff2": "font/woff2" };
+
+function serveFile(req, res) {
+  let pathname;
+  try { pathname = decodeURIComponent(new URL(req.url, `http://${host}`).pathname); }
+  catch { res.writeHead(400).end(); return; }
+  if (pathname.includes("\0") || pathname.split("/").includes("..")) { res.writeHead(400).end(); return; }
+  const target = path.resolve(distDir, `.${pathname}`);
+  if (target !== distDir && !target.startsWith(`${distDir}${path.sep}`)) { res.writeHead(403).end(); return; }
+  const file = fs.existsSync(target) && fs.statSync(target).isFile() ? target : path.join(distDir, "index.html");
+  if (!fs.existsSync(file)) { res.writeHead(503).end("Web 页面尚未构建"); return; }
+  res.writeHead(200, { "Content-Type": mime[path.extname(file)] || "application/octet-stream", "Cache-Control": file.endsWith("index.html") ? "no-cache" : "public, max-age=3600" });
+  fs.createReadStream(file).pipe(res);
+}
+
+const server = http.createServer((req, res) => {
+  if (req.url === "/api/web/health") {
+    res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+    res.end(JSON.stringify({ service: "rexp-hub-web", pid: process.pid }));
+    return;
+  }
+  if (req.url?.startsWith("/api/")) { void handleApi(req, res, () => res.writeHead(404).end()); return; }
+  if (req.method !== "GET" && req.method !== "HEAD") { res.writeHead(405).end(); return; }
+  handleApi(req, res, () => serveFile(req, res));
+});
+
+let stopping = false;
+async function stop(exitCode = 0) {
+  if (stopping) return;
+  stopping = true;
+  try { await closeBridge(); } catch (error) { console.error(error); exitCode = 1; }
+  await Promise.race([
+    new Promise((resolve) => { server.close(resolve); server.closeAllConnections(); }),
+    new Promise((resolve) => setTimeout(resolve, 2000)),
+  ]);
+  try {
+    const state = JSON.parse(fs.readFileSync(pidFile, "utf8"));
+    if (state.pid === process.pid) fs.unlinkSync(pidFile);
+  } catch { /* A removed state file needs no cleanup. */ }
+  process.exit(exitCode);
+}
+
+process.on("SIGINT", () => { void stop(); });
+process.on("SIGTERM", () => { void stop(); });
+process.on("uncaughtException", (error) => { console.error(error); void stop(1); });
+
+if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error("REXP_WEB_PORT 必须是有效端口");
+server.once("error", (error) => { console.error(error); process.exitCode = 1; });
+server.listen(port, host, () => {
+  fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(pidFile, JSON.stringify({ pid: process.pid, port, projectDir }), { mode: 0o600 });
+  console.log(`REXP Hub 已启动：http://${host}:${port}/`);
+});

package/skills/web-operations.md

@@ -0,0 +1,38 @@
+# REXP Web 使用说明
+
+REXP Web 在 SSH-MCP 所在的控制端运行。通过 SSH-MCP 的 `plugin-run`，选择
+`plugin: rexp-web`，传入下面的 argv 即可管理；不要传远端 connectionName。
+
+## 首次安装
+
+1. 安装后先询问用户是否开启登录系统后自动启动。安装包本身不会修改系统启动项。
+   用户已明确提供选择或委托时沿用其选择，不重复询问。
+2. 执行 `configure --autostart on` 或 `configure --autostart off`。
+   该步骤保存宿主提供的 SSH-MCP 程序和个人配置路径，登录启动后仍使用同一份配置。
+3. 执行 `open`，后台启动并打开浏览器。提醒用户将页面加入书签，下次直接打开。
+
+## 生命周期命令
+
+- `status --json`：查看服务地址、运行状态和自启动设置。
+- `start`：后台启动；已运行则复用，不重复启动。不会更改自启动偏好。
+- `open`：确保服务启动，随后打开控制台并提示添加书签。
+- `stop`：明确停止 Web。保留自启动选择，远端实验和 Agent 的 SSH-MCP 不受影响。
+- `autostart status --json`、`autostart on`、`autostart off`：查询或修改登录启动。
+  关闭自启动只影响下次登录，不关闭当前 Web。网页右上角设置也能修改同一个开关。
+- `logs`：读取后台日志。`version --json`：查询版本。
+
+程序安装位置、配置和启动项都属于 MCP 宿主，不属于远端实验服务器。
+系统启动环境可能没有终端 PATH，因此启动项使用绝对 Node 和程序路径。
+macOS、Windows 与 Linux 桌面支持用户登录时启动，不需要系统管理员权限。
+无桌面的 Linux 暂不自动安装系统服务，应说明限制，保留手动/MCP 启动方式。
+
+## 使用约定
+
+Agent 退出不应停止 Web；只有用户明确要求关闭时才执行 stop。
+用户未开启自启动时，可随时通过 MCP 的 open 恢复使用。
+若用户通过 Agent 提交实验并希望网页监测，先查 status；未运行时询问是否启动，
+拒绝后本次会话不重复询问，也不阻塞实验提交。此约定是 Agent 指引，不是对所有
+REXP 提交命令的自动拦截；不修改远端实验调度器。
+关闭所有网页后停止相关远端监测，后台服务保留待命。
+
+不要复制 SSH 密码到 Web 项目或启动项，也不要修改远端平台来启停本地 Web。