@mearl/cloud-server 2.0.0

package/README.md

@@ -0,0 +1,214 @@
+# @mearl/cloud-server
+
+云端 WebSocket Server，用于中转云端 Agent 请求到本地连接器。
+
+## 安装
+
+```bash
+npm install -g @mearl/cloud-server
+# 或
+pnpm add -g @mearl/cloud-server
+```
+
+## 使用
+
+### 命令行方式
+
+Server **默认以后台守护进程方式运行**，启动后立即返回，并打印本地机器需要执行的连接命令。
+
+```bash
+mearl-cloud-server [command] [options]
+```
+
+**子命令：**
+- `start` - 后台启动 server（默认，不写也等价于 `start`）
+- `stop` - 停止后台 server
+- `restart` - 重启后台 server
+- `status` - 查看运行状态及连接信息
+- `logs` - 打印 server 日志末尾
+
+**选项：**
+- `--foreground` / `-f` - 前台运行（不守护化，适合 systemd / Docker / PM2）
+- `--port <port>` - 服务器端口（默认 8080）
+- `--path <path>` - WebSocket 路径（默认 /ws）
+- `--token <token>` - 鉴权密钥（未指定时自动生成）
+- `--heartbeat <seconds>` - 心跳超时时间（默认 90 秒）
+- `--max-connections <n>` - 最大连接数（默认 100）
+
+**示例：**
+```bash
+# 后台启动（自动生成 token），打印连接命令后立即返回
+mearl-cloud-server
+
+# 查看状态与连接信息
+mearl-cloud-server status
+
+# 停止 / 重启
+mearl-cloud-server stop
+mearl-cloud-server restart
+
+# 自定义端口和鉴权
+mearl-cloud-server start --port 9000 --token your-secret-token
+
+# 前台运行（交给外部进程管理器托管）
+mearl-cloud-server --foreground
+```
+
+后台启动后会打印供本地机器使用的连接命令，例如：
+```
+[CloudServer] Started in background (pid 12345)
+[CloudServer] Logs: ~/.mearl/cloud-server.log
+
+  Connect from your local machine:
+    npx @mearl/cloud-connector "ws://10.0.1.100:8080/ws?token=xxx"
+```
+
+运行时文件位于 `~/.mearl/`：
+- `cloud-server.json` - 连接配置（含 server URL、pid、端口等），cloud-client 自动读取
+- `cloud-server.log` - 后台进程日志（`logs` 子命令读取，或 `tail -f` 跟踪）；超过 5MB 会在下次启动时滚动为 `cloud-server.log.1`
+
+> 守护进程的启停、状态、日志滚动等生命周期逻辑由共享包 [`@mearl/daemon-core`](../../daemon-core) 提供（与 cloud-connector 复用同一套实现）。
+
+**关于 token：**
+- 未指定 `--token` 时会自动生成。`restart` 会**沿用当前 token**，因此之前打印的连接命令重启后仍然有效。
+- `stop` 后再 `start` 属于全新启动，会重新生成 token；若希望连接命令长期固定，请显式传入 `--token` 或设置 `MEARL_TOKEN`。
+
+**环境变量：**
+- `MEARL_TOKEN` - 鉴权密钥（覆盖 --token 选项）
+- `CLOUD_SERVER_HOST` - 公网主机名（默认自动获取）
+
+### 编程方式
+
+```typescript
+import { CloudServer } from '@mearl/cloud-server';
+
+const server = new CloudServer({
+  port: 8080,
+  path: '/ws',
+  token: 'your-secret-token',
+  heartbeatTimeout: 90,
+  maxConnections: 100,
+  maxMessageSize: 10 * 1024 * 1024,
+});
+
+await server.start();
+
+// 获取统计信息
+const stats = server.getStats();
+console.log(stats);
+// { connections: 2, agents: 1, connectors: 1, pendingRequests: 0 }
+
+// 优雅关闭
+await server.stop();
+```
+
+## 架构
+
+```
+云端 Agent
+  ↓
+@mearl/cloud-client
+  ↓ (WebSocket)
+@mearl/cloud-server (本进程)
+  ↓ (WebSocket)
+@mearl/cloud-connector (本地)
+  ↓ (Unix Socket)
+@mearl/native-host
+  ↓
+Chrome Extension / CDP
+```
+
+## 连接类型
+
+Server 接受两种类型的连接：
+
+1. **Agent 连接** - 发起请求的云端客户端
+2. **Connector 连接** - 转发请求到 native-host 的本地连接器
+
+Server 会自动识别连接类型，并将 Agent 的请求转发到可用的 Connector。
+
+## 消息协议
+
+### 请求格式（Agent → Server）
+```json
+{
+  "id": "unique-id",
+  "action": "get_requests",
+  "data": { "count": 5 },
+  "version": "1.30.0"
+}
+```
+
+### 响应格式（Server → Agent）
+```json
+{
+  "id": "unique-id",
+  "success": true,
+  "data": { ... },
+  "versionWarning": "..."
+}
+```
+
+### 心跳格式
+```json
+{ "type": "ping", "timestamp": 1234567890 }
+{ "type": "pong", "timestamp": 1234567890 }
+```
+
+## 鉴权
+
+设置 `token` 后，所有连接必须携带正确的 token：
+
+```bash
+# Agent 连接
+ws://server.com/ws?token=your-secret-token
+
+# Connector 连接
+ws://server.com/ws?token=your-secret-token
+```
+
+## 部署建议
+
+> 交给外部进程管理器（systemd / Docker / PM2）托管时，请加 `--foreground`，让 server 在前台运行，由管理器负责守护与重启。
+
+### 使用 systemd（Linux）
+
+```ini
+[Unit]
+Description=Mearl Cloud Server
+After=network.target
+
+[Service]
+Type=simple
+User=your-user
+ExecStart=/usr/bin/mearl-cloud-server --foreground --port 8080 --token your-token
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### 使用 Docker
+
+```dockerfile
+FROM node:20-alpine
+RUN npm install -g @mearl/cloud-server
+EXPOSE 8080
+CMD ["mearl-cloud-server", "--foreground", "--token", "your-token"]
+```
+
+### 使用 PM2
+
+```bash
+pm2 start mearl-cloud-server --name mtop-cloud-server -- --foreground --port 8080 --token your-token
+```
+
+## 注意事项
+
+- 建议在生产环境使用 WSS（WebSocket Secure）加密传输
+- 使用反向代理（如 Nginx）处理 WSS 升级
+- 设置合理的 `maxConnections` 限制资源占用
+- 启用 `token` 鉴权保护服务安全
+- 在沙箱环境中启动时，会自动检测并使用平台分配的公网地址
+- 如果沙箱端口映射 API 不可用，会回退到使用本地 IP 地址

package/dist/__tests__/routing.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,609 @@
+#!/usr/bin/env node
+
+// src/daemon.ts
+import { fileURLToPath } from "node:url";
+import { createDaemon, readRecord, removeRecord } from "@mearl/daemon-core";
+
+// src/index.ts
+import WebSocket, { WebSocketServer } from "ws";
+import { createServer as createHttpServer } from "node:http";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { networkInterfaces } from "node:os";
+
+// src/paths.ts
+import { join } from "node:path";
+import { DAEMON_HOME } from "@mearl/daemon-core";
+var CONFIG_DIR = DAEMON_HOME;
+var CONFIG_FILE = join(CONFIG_DIR, "cloud-server.json");
+var LOG_FILE = join(CONFIG_DIR, "cloud-server.log");
+
+// src/index.ts
+import {
+  isHeartbeatMessage,
+  isCloudMessage,
+  isCloudResponse,
+  MAX_BUFFER_SIZE,
+  DEFAULT_HEARTBEAT_TIMEOUT,
+  DEFAULT_REQUEST_TIMEOUT
+} from "@mearl/cloud-types";
+import { resolveActionTimeoutSec } from "@mearl/client/action-timeouts";
+var fetchInstance = null;
+async function getFetch() {
+  if (fetchInstance) {
+    return fetchInstance;
+  }
+  if (typeof globalThis.fetch !== "undefined") {
+    fetchInstance = globalThis.fetch;
+  } else {
+    const { default: fetch } = await import("node-fetch");
+    fetchInstance = fetch;
+  }
+  return fetchInstance;
+}
+var DEFAULT_PORT = 8080;
+var DEFAULT_PATH = "/ws";
+var DEFAULT_MAX_CONNECTIONS = 100;
+var DEFAULT_MAX_MESSAGE_SIZE = 10 * 1024 * 1024;
+var RESPONSE_GRACE_MS = 5e3;
+var CloudServer = class {
+  options;
+  connectorWss = null;
+  agentWss = null;
+  connectorHttpServer = null;
+  agentHttpServer = null;
+  connections = /* @__PURE__ */ new Map();
+  pendingRequests = /* @__PURE__ */ new Map();
+  heartbeatTimer = null;
+  constructor(options = {}) {
+    const port = options.port ?? DEFAULT_PORT;
+    this.options = {
+      port,
+      agentPort: options.agentPort ?? port + 1,
+      path: options.path ?? DEFAULT_PATH,
+      token: options.token,
+      heartbeatTimeout: options.heartbeatTimeout ?? DEFAULT_HEARTBEAT_TIMEOUT,
+      maxConnections: options.maxConnections ?? DEFAULT_MAX_CONNECTIONS,
+      maxMessageSize: options.maxMessageSize ?? DEFAULT_MAX_MESSAGE_SIZE,
+      requestTimeout: options.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT,
+      allowRemoteAgent: options.allowRemoteAgent ?? false
+    };
+  }
+  getToken() {
+    if (!this.options.token) {
+      this.options.token = this.generateRandomToken();
+    }
+    return this.options.token;
+  }
+  generateRandomToken() {
+    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+    let token = "";
+    for (let i = 0; i < 32; i++) {
+      token += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return token;
+  }
+  async start() {
+    await this.createListener(this.options.agentPort, "127.0.0.1", true);
+    await this.createListener(this.options.port, "0.0.0.0", false);
+    const token = this.getToken();
+    const localWsUrl = `ws://localhost:${this.options.agentPort}${this.options.path}?token=${token}`;
+    let publicWsUrl;
+    const sandboxUrl = await this.getSandboxPublicUrl(this.options.port);
+    if (sandboxUrl) {
+      try {
+        const parsedUrl = new URL(sandboxUrl);
+        parsedUrl.protocol = "wss:";
+        parsedUrl.pathname = this.options.path;
+        parsedUrl.search = `?token=${token}`;
+        publicWsUrl = parsedUrl.toString();
+      } catch {
+        const httpsUrl = sandboxUrl.replace("https://", "wss://");
+        publicWsUrl = `${httpsUrl}${this.options.path}?token=${token}`;
+      }
+    } else {
+      const publicHost = process.env.CLOUD_SERVER_HOST || this.getPublicIP();
+      publicWsUrl = `ws://${publicHost}:${this.options.port}${this.options.path}?token=${token}`;
+    }
+    const connectorCommand = `npx @mearl/cloud-connector "${publicWsUrl}"`;
+    console.log(
+      `[CloudServer] Connector listener on 0.0.0.0:${this.options.port} (network); agent listener on 127.0.0.1:${this.options.agentPort} (local only)`
+    );
+    console.log(`[CloudServer] Connect from local machine:`);
+    console.log(`  ${connectorCommand}`);
+    this.startHeartbeatCheck();
+    const info = {
+      pid: process.pid,
+      port: this.options.port,
+      path: this.options.path,
+      token,
+      localUrl: localWsUrl,
+      publicUrl: publicWsUrl,
+      connectorCommand,
+      startedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.writeConfigFile(info);
+    return info;
+  }
+  /**
+   * Stand up one HTTP+WebSocket listener. `fromLocal` tags every connection
+   * accepted here so handleRequest can pin command-issuing authority to the
+   * loopback listener.
+   */
+  createListener(port, host, fromLocal) {
+    return new Promise((resolve, reject) => {
+      const httpServer = createHttpServer((req, res) => {
+        console.log(`[CloudServer] HTTP request: ${req.method} ${req.url}`);
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("Not Found - This is a WebSocket server");
+      });
+      const wss = new WebSocketServer({
+        server: httpServer,
+        path: this.options.path,
+        maxPayload: this.options.maxMessageSize
+      });
+      wss.on("connection", (ws, req) => {
+        console.log(
+          `[CloudServer] New ${fromLocal ? "agent" : "connector"} connection from ${req.socket.remoteAddress}, path: ${req.url}`
+        );
+        this.handleConnection(ws, req, fromLocal);
+      });
+      wss.on("error", (error) => {
+        console.error("[CloudServer] WebSocket server error:", error.message);
+      });
+      httpServer.on("error", (error) => {
+        console.error("[CloudServer] HTTP server error:", error.message);
+        reject(error);
+      });
+      if (fromLocal) {
+        this.agentWss = wss;
+        this.agentHttpServer = httpServer;
+      } else {
+        this.connectorWss = wss;
+        this.connectorHttpServer = httpServer;
+      }
+      httpServer.listen(port, host, () => {
+        resolve();
+      });
+    });
+  }
+  stop() {
+    return new Promise((resolve) => {
+      if (this.heartbeatTimer) {
+        clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = null;
+      }
+      for (const [ws] of this.connections) {
+        ws.close();
+      }
+      this.connections.clear();
+      this.pendingRequests.clear();
+      this.agentWss?.close();
+      this.connectorWss?.close();
+      this.agentWss = null;
+      this.connectorWss = null;
+      const servers = [this.agentHttpServer, this.connectorHttpServer].filter(
+        (s) => s !== null
+      );
+      this.agentHttpServer = null;
+      this.connectorHttpServer = null;
+      if (servers.length === 0) {
+        resolve();
+        return;
+      }
+      let remaining = servers.length;
+      for (const s of servers) {
+        s.close(() => {
+          if (--remaining <= 0) resolve();
+        });
+      }
+    });
+  }
+  handleConnection(ws, req, fromLocal) {
+    if (this.connections.size >= this.options.maxConnections) {
+      ws.close(1008, "Server is full");
+      return;
+    }
+    if (this.options.token) {
+      const url = new URL(req.url || "", `http://${req.headers.host}`);
+      const token = url.searchParams.get("token");
+      if (token !== this.options.token) {
+        ws.close(1008, "Unauthorized");
+        return;
+      }
+    }
+    const connId = `${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+    const connection = {
+      ws,
+      id: connId,
+      lastHeartbeat: Date.now(),
+      isAgent: false,
+      fromLocal,
+      messageBuffer: ""
+    };
+    this.connections.set(ws, connection);
+    console.log(`[CloudServer] Client connected: ${connId} (total: ${this.connections.size})`);
+    ws.on("message", (data) => {
+      const conn = this.connections.get(ws);
+      if (!conn) return;
+      conn.messageBuffer += data.toString("utf-8");
+      if (conn.messageBuffer.length > MAX_BUFFER_SIZE) {
+        console.error(
+          `[CloudServer] Message buffer exceeds limit for ${connId}, closing connection`
+        );
+        ws.close(1008, "Message too large");
+        return;
+      }
+      let newlineIndex;
+      while ((newlineIndex = conn.messageBuffer.indexOf("\n")) !== -1) {
+        const line = conn.messageBuffer.slice(0, newlineIndex);
+        conn.messageBuffer = conn.messageBuffer.slice(newlineIndex + 1);
+        if (!line.trim()) continue;
+        try {
+          const message = JSON.parse(line);
+          this.handleMessage(ws, message, connId);
+        } catch (error) {
+          console.error(`[CloudServer] Failed to parse message from ${connId}:`, line, error);
+        }
+      }
+    });
+    ws.on("close", () => {
+      this.connections.delete(ws);
+      this.rejectPendingForWs(ws);
+      console.log(`[CloudServer] Client disconnected: ${connId} (total: ${this.connections.size})`);
+    });
+    ws.on("error", (error) => {
+      console.error(`[CloudServer] Connection error for ${connId}:`, error.message);
+    });
+  }
+  handleMessage(ws, message, connId) {
+    const conn = this.connections.get(ws);
+    if (!conn) return;
+    if (isHeartbeatMessage(message)) {
+      if (message.type === "ping") {
+        ws.send(
+          JSON.stringify({ type: "pong", timestamp: Date.now() }) + "\n"
+        );
+        conn.lastHeartbeat = Date.now();
+      } else if (message.type === "pong") {
+        conn.lastHeartbeat = Date.now();
+      }
+      return;
+    }
+    if (isCloudResponse(message)) {
+      this.handleResponse(ws, message, connId);
+      return;
+    }
+    if (isCloudMessage(message)) {
+      this.handleRequest(ws, message, connId);
+      return;
+    }
+  }
+  handleRequest(ws, message, _connId) {
+    const { id, action, data } = message;
+    const conn = this.connections.get(ws);
+    if (!conn) return;
+    if (!conn.fromLocal && !this.options.allowRemoteAgent) {
+      console.warn(
+        `[CloudServer] Rejected agent request from non-local connection ${conn.id} (action: ${action})`
+      );
+      ws.send(
+        JSON.stringify({
+          id,
+          success: false,
+          error: "Agent requests are only accepted on the local interface (127.0.0.1). Run cloud-client on the same machine as cloud-server, or start the server with --allow-remote-agent to override."
+        }) + "\n"
+      );
+      ws.close(1008, "Agent must be local");
+      return;
+    }
+    conn.isAgent = true;
+    const targetWs = this.findConnector();
+    if (!targetWs) {
+      ws.send(JSON.stringify({ id, success: false, error: "No local connector available" }) + "\n");
+      return;
+    }
+    const requestedTimeoutSec = Number(message.timeoutSec);
+    const timeoutSec = Number.isFinite(requestedTimeoutSec) && requestedTimeoutSec > 0 ? Math.min(requestedTimeoutSec, 3600) : resolveActionTimeoutSec(action, data, this.options.requestTimeout);
+    const timer = setTimeout(
+      () => {
+        this.pendingRequests.delete(id);
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.send(JSON.stringify({ id, success: false, error: "Request timeout" }) + "\n");
+        }
+      },
+      timeoutSec * 1e3 + RESPONSE_GRACE_MS
+    );
+    this.pendingRequests.set(id, { ws, timer });
+    targetWs.send(
+      JSON.stringify({ id, action, data, browser: message.browser, timeoutSec }) + "\n"
+    );
+  }
+  handleResponse(ws, response, _connId) {
+    const conn = this.connections.get(ws);
+    if (!conn) return;
+    if (conn.isAgent) return;
+    const pending = this.pendingRequests.get(response.id);
+    if (!pending) return;
+    this.pendingRequests.delete(response.id);
+    clearTimeout(pending.timer);
+    if (pending.ws.readyState === WebSocket.OPEN) {
+      pending.ws.send(JSON.stringify(response) + "\n");
+    }
+  }
+  findConnector() {
+    for (const [ws, conn] of this.connections) {
+      if (!conn.isAgent && ws.readyState === WebSocket.OPEN) {
+        return ws;
+      }
+    }
+    return null;
+  }
+  rejectPendingForWs(ws) {
+    this.pendingRequests.forEach((pending, id) => {
+      if (pending.ws === ws) {
+        clearTimeout(pending.timer);
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.send(JSON.stringify({ id, success: false, error: "Connection closed" }) + "\n");
+        }
+        this.pendingRequests.delete(id);
+      }
+    });
+  }
+  startHeartbeatCheck() {
+    if (this.heartbeatTimer) return;
+    this.heartbeatTimer = setInterval(() => {
+      const now = Date.now();
+      const timeoutMs = this.options.heartbeatTimeout * 1e3;
+      for (const [ws, conn] of this.connections) {
+        if (now - conn.lastHeartbeat > timeoutMs) {
+          console.log(`[CloudServer] Client ${conn.id} heartbeat timeout, closing connection`);
+          ws.close(1e3, "Heartbeat timeout");
+        }
+      }
+    }, 3e4);
+  }
+  getPublicIP() {
+    const interfaces = networkInterfaces();
+    for (const name of Object.keys(interfaces)) {
+      const iface = interfaces[name];
+      if (!iface) continue;
+      for (const addr of iface) {
+        if (addr.family === "IPv4" && !addr.internal) {
+          return addr.address;
+        }
+      }
+    }
+    return "localhost";
+  }
+  async getSandboxPublicUrl(port) {
+    if (!process.env.AONE_SANDBOX_ID) {
+      return null;
+    }
+    const mappingApiUrl = "http://localhost:58596/api/port-mapping";
+    try {
+      const fetch = await getFetch();
+      const response = await fetch(`${mappingApiUrl}?port=${port}`);
+      if (!response.ok) {
+        return null;
+      }
+      const data = await response.json();
+      if (data.success && data.url) {
+        return data.url;
+      }
+    } catch (error) {
+      console.error(
+        `[CloudServer] Failed to query sandbox port mapping:`,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+    return null;
+  }
+  writeConfigFile(info) {
+    try {
+      if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+      }
+      const config = { server: info.localUrl, ...info };
+      writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
+      console.log(`[CloudServer] Config written to: ${CONFIG_FILE}`);
+    } catch (error) {
+      console.error("[CloudServer] Failed to write config file:", error);
+    }
+  }
+  getStats() {
+    let agents = 0;
+    let connectors = 0;
+    for (const conn of this.connections.values()) {
+      if (conn.isAgent) agents++;
+      else connectors++;
+    }
+    return {
+      connections: this.connections.size,
+      agents,
+      connectors,
+      pendingRequests: this.pendingRequests.size
+    };
+  }
+};
+
+// src/daemon.ts
+var SCRIPT_PATH = fileURLToPath(import.meta.url);
+function formatConnectInfo(record) {
+  const config = record;
+  const lines = [];
+  if (config.port) lines.push(`  port:       ${config.port}`);
+  const command2 = config.connectorCommand || (config.publicUrl ? `npx @mearl/cloud-connector "${config.publicUrl}"` : null);
+  if (command2) {
+    lines.push("");
+    lines.push("  Connect from your local machine:");
+    lines.push(`    ${command2}`);
+  }
+  return lines.length ? lines.join("\n") : null;
+}
+function daemon(foregroundArgs) {
+  return createDaemon({
+    name: "CloudServer",
+    scriptPath: SCRIPT_PATH,
+    configFile: CONFIG_FILE,
+    logFile: LOG_FILE,
+    foregroundArgs,
+    formatInfo: formatConnectInfo
+  });
+}
+function startDaemon(passthroughArgs) {
+  return daemon(passthroughArgs).start();
+}
+function stopDaemon() {
+  return daemon([]).stop();
+}
+function restartDaemon(passthroughArgs) {
+  let args = passthroughArgs;
+  if (!passthroughArgs.includes("--token") && !process.env.MEARL_TOKEN) {
+    const token = readRecord(CONFIG_FILE)?.token;
+    if (token) args = [...passthroughArgs, "--token", token];
+  }
+  return daemon(args).restart();
+}
+function statusDaemon() {
+  daemon([]).status();
+}
+function printLogs() {
+  daemon([]).logs();
+}
+async function runForeground(options) {
+  const server = new CloudServer(options);
+  await server.start();
+  console.log("[CloudServer] Press Ctrl+C to stop");
+  let shuttingDown = false;
+  const shutdown = async (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    console.log(`
+[CloudServer] Received ${signal}, shutting down...`);
+    await server.stop();
+    removeRecord(CONFIG_FILE);
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void shutdown("SIGINT"));
+  process.on("SIGTERM", () => void shutdown("SIGTERM"));
+}
+
+// src/cli.ts
+var CLOUD_SERVER_VERSION = true ? "2.0.0" : "unknown";
+var argv = process.argv.slice(2);
+if (argv.includes("--version") || argv.includes("-v")) {
+  console.log(CLOUD_SERVER_VERSION);
+  process.exit(0);
+}
+if (argv.includes("--help") || argv.includes("-h")) {
+  showHelp();
+  process.exit(0);
+}
+var COMMANDS = ["start", "stop", "restart", "status", "logs"];
+var command = "start";
+var rest = argv;
+if (argv[0] && COMMANDS.includes(argv[0])) {
+  command = argv[0];
+  rest = argv.slice(1);
+}
+var foreground = rest.includes("--foreground") || rest.includes("-f");
+function showHelp() {
+  console.log(`mearl-cloud-server v${CLOUD_SERVER_VERSION}
+
+Usage:
+  mearl-cloud-server [command] [options]
+
+Commands:
+  start                      Start the server in the background (default)
+  stop                       Stop the background server
+  restart                    Restart the background server
+  status                     Show whether the server is running + connect info
+  logs                       Print the tail of the server log
+
+Options:
+  --foreground, -f           Run in the foreground instead of daemonizing
+  --port <port>              Connector (network) port (default: 8080)
+  --agent-port <port>        Agent port, bound to 127.0.0.1 only (default: port + 1)
+  --path <path>              WebSocket path (default: /ws)
+  --token <token>            Authentication token (auto-generated if not specified)
+  --heartbeat <seconds>      Heartbeat timeout in seconds (default: 90)
+  --max-connections <n>      Max concurrent connections (default: 100)
+  --allow-remote-agent       Allow command-issuing agents to connect from the
+                             network (default: off; agents must be local)
+  --version, -v              Show version
+  --help, -h                 Show this help message
+
+Environment Variables:
+  MEARL_TOKEN        Authentication token (overrides --token if set)
+  CLOUD_SERVER_HOST          Host name for WebSocket URL (default: localhost)
+
+Examples:
+  # Start in the background (default) and print the connector command
+  mearl-cloud-server
+
+  # Check status / connect info, then stop
+  mearl-cloud-server status
+  mearl-cloud-server stop
+
+  # Start with a custom port and token
+  mearl-cloud-server start --port 9000 --token your-secret-token
+
+  # Run in the foreground (e.g. under systemd / Docker / PM2)
+  mearl-cloud-server --foreground
+`);
+}
+function parseOptions(args) {
+  const options = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--port" && i + 1 < args.length) {
+      options.port = parseInt(args[++i], 10);
+    } else if (arg === "--agent-port" && i + 1 < args.length) {
+      options.agentPort = parseInt(args[++i], 10);
+    } else if (arg === "--path" && i + 1 < args.length) {
+      options.path = args[++i];
+    } else if (arg === "--token" && i + 1 < args.length) {
+      options.token = args[++i];
+    } else if (arg === "--heartbeat" && i + 1 < args.length) {
+      options.heartbeatTimeout = parseInt(args[++i], 10);
+    } else if (arg === "--max-connections" && i + 1 < args.length) {
+      options.maxConnections = parseInt(args[++i], 10);
+    } else if (arg === "--allow-remote-agent") {
+      options.allowRemoteAgent = true;
+    }
+  }
+  if (!options.token) {
+    const envToken = process.env.MEARL_TOKEN;
+    if (envToken) {
+      options.token = envToken;
+    }
+  }
+  return options;
+}
+async function main() {
+  if (foreground) {
+    await runForeground(parseOptions(rest));
+    return;
+  }
+  switch (command) {
+    case "start":
+      await startDaemon(rest);
+      break;
+    case "stop":
+      await stopDaemon();
+      break;
+    case "restart":
+      await restartDaemon(rest);
+      break;
+    case "status":
+      statusDaemon();
+      break;
+    case "logs":
+      printLogs();
+      break;
+  }
+}
+main().catch((error) => {
+  console.error("[CloudServer] Fatal error:", error);
+  process.exit(1);
+});

package/dist/daemon.d.ts

@@ -0,0 +1,22 @@
+import { CloudServerOptions } from './index.js';
+/** Spawn the server as a detached background process. */
+export declare function startDaemon(passthroughArgs: string[]): Promise<void>;
+/** Stop a running background server. */
+export declare function stopDaemon(): Promise<void>;
+/**
+ * Restart the background server, preserving the existing (auto-generated) token
+ * unless the caller overrides it, so the previously-shared connector command
+ * keeps working across a restart.
+ */
+export declare function restartDaemon(passthroughArgs: string[]): Promise<void>;
+/** Print whether a background server is running and how to connect to it. */
+export declare function statusDaemon(): void;
+/** Print the tail of the daemon log file. */
+export declare function printLogs(): void;
+/**
+ * Run the server in the current process (no daemonizing). Used internally by
+ * the detached child, and available to users via `--foreground`. The server
+ * writes its own `ServerInfo` (including `pid`) into the config file once it is
+ * listening — that pid is how the daemon manager confirms the child came up.
+ */
+export declare function runForeground(options: CloudServerOptions): Promise<void>;

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+export interface CloudServerOptions {
+    port?: number;
+    /** Loopback-only port for the co-located agent (cloud-client). Defaults to port + 1. */
+    agentPort?: number;
+    path?: string;
+    token?: string;
+    heartbeatTimeout?: number;
+    maxConnections?: number;
+    maxMessageSize?: number;
+    requestTimeout?: number;
+    /** Escape hatch: allow agents (command issuers) to connect from the network. Default false. */
+    allowRemoteAgent?: boolean;
+}
+/** Runtime info about a started server, also persisted to the config file. */
+export interface ServerInfo {
+    pid: number;
+    port: number;
+    path: string;
+    token: string;
+    /** URL for a cloud-client running on the same machine (localhost). */
+    localUrl: string;
+    /** URL for the local connector to dial back into this server. */
+    publicUrl: string;
+    /** Ready-to-paste command for the local machine. */
+    connectorCommand: string;
+    /** ISO timestamp of when the server started listening. */
+    startedAt: string;
+}
+export declare class CloudServer {
+    private options;
+    private connectorWss;
+    private agentWss;
+    private connectorHttpServer;
+    private agentHttpServer;
+    private connections;
+    private pendingRequests;
+    private heartbeatTimer;
+    constructor(options?: CloudServerOptions);
+    getToken(): string;
+    private generateRandomToken;
+    start(): Promise<ServerInfo>;
+    /**
+     * Stand up one HTTP+WebSocket listener. `fromLocal` tags every connection
+     * accepted here so handleRequest can pin command-issuing authority to the
+     * loopback listener.
+     */
+    private createListener;
+    stop(): Promise<void>;
+    private handleConnection;
+    private handleMessage;
+    private handleRequest;
+    private handleResponse;
+    private findConnector;
+    private rejectPendingForWs;
+    private startHeartbeatCheck;
+    private getPublicIP;
+    private getSandboxPublicUrl;
+    private writeConfigFile;
+    getStats(): {
+        connections: number;
+        agents: number;
+        connectors: number;
+        pendingRequests: number;
+    };
+}

package/dist/index.js

@@ -0,0 +1,424 @@
+// src/index.ts
+import WebSocket, { WebSocketServer } from "ws";
+import { createServer as createHttpServer } from "node:http";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { networkInterfaces } from "node:os";
+
+// src/paths.ts
+import { join } from "node:path";
+import { DAEMON_HOME } from "@mearl/daemon-core";
+var CONFIG_DIR = DAEMON_HOME;
+var CONFIG_FILE = join(CONFIG_DIR, "cloud-server.json");
+var LOG_FILE = join(CONFIG_DIR, "cloud-server.log");
+
+// src/index.ts
+import {
+  isHeartbeatMessage,
+  isCloudMessage,
+  isCloudResponse,
+  MAX_BUFFER_SIZE,
+  DEFAULT_HEARTBEAT_TIMEOUT,
+  DEFAULT_REQUEST_TIMEOUT
+} from "@mearl/cloud-types";
+import { resolveActionTimeoutSec } from "@mearl/client/action-timeouts";
+var fetchInstance = null;
+async function getFetch() {
+  if (fetchInstance) {
+    return fetchInstance;
+  }
+  if (typeof globalThis.fetch !== "undefined") {
+    fetchInstance = globalThis.fetch;
+  } else {
+    const { default: fetch } = await import("node-fetch");
+    fetchInstance = fetch;
+  }
+  return fetchInstance;
+}
+var DEFAULT_PORT = 8080;
+var DEFAULT_PATH = "/ws";
+var DEFAULT_MAX_CONNECTIONS = 100;
+var DEFAULT_MAX_MESSAGE_SIZE = 10 * 1024 * 1024;
+var RESPONSE_GRACE_MS = 5e3;
+var CloudServer = class {
+  options;
+  connectorWss = null;
+  agentWss = null;
+  connectorHttpServer = null;
+  agentHttpServer = null;
+  connections = /* @__PURE__ */ new Map();
+  pendingRequests = /* @__PURE__ */ new Map();
+  heartbeatTimer = null;
+  constructor(options = {}) {
+    const port = options.port ?? DEFAULT_PORT;
+    this.options = {
+      port,
+      agentPort: options.agentPort ?? port + 1,
+      path: options.path ?? DEFAULT_PATH,
+      token: options.token,
+      heartbeatTimeout: options.heartbeatTimeout ?? DEFAULT_HEARTBEAT_TIMEOUT,
+      maxConnections: options.maxConnections ?? DEFAULT_MAX_CONNECTIONS,
+      maxMessageSize: options.maxMessageSize ?? DEFAULT_MAX_MESSAGE_SIZE,
+      requestTimeout: options.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT,
+      allowRemoteAgent: options.allowRemoteAgent ?? false
+    };
+  }
+  getToken() {
+    if (!this.options.token) {
+      this.options.token = this.generateRandomToken();
+    }
+    return this.options.token;
+  }
+  generateRandomToken() {
+    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+    let token = "";
+    for (let i = 0; i < 32; i++) {
+      token += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return token;
+  }
+  async start() {
+    await this.createListener(this.options.agentPort, "127.0.0.1", true);
+    await this.createListener(this.options.port, "0.0.0.0", false);
+    const token = this.getToken();
+    const localWsUrl = `ws://localhost:${this.options.agentPort}${this.options.path}?token=${token}`;
+    let publicWsUrl;
+    const sandboxUrl = await this.getSandboxPublicUrl(this.options.port);
+    if (sandboxUrl) {
+      try {
+        const parsedUrl = new URL(sandboxUrl);
+        parsedUrl.protocol = "wss:";
+        parsedUrl.pathname = this.options.path;
+        parsedUrl.search = `?token=${token}`;
+        publicWsUrl = parsedUrl.toString();
+      } catch {
+        const httpsUrl = sandboxUrl.replace("https://", "wss://");
+        publicWsUrl = `${httpsUrl}${this.options.path}?token=${token}`;
+      }
+    } else {
+      const publicHost = process.env.CLOUD_SERVER_HOST || this.getPublicIP();
+      publicWsUrl = `ws://${publicHost}:${this.options.port}${this.options.path}?token=${token}`;
+    }
+    const connectorCommand = `npx @mearl/cloud-connector "${publicWsUrl}"`;
+    console.log(
+      `[CloudServer] Connector listener on 0.0.0.0:${this.options.port} (network); agent listener on 127.0.0.1:${this.options.agentPort} (local only)`
+    );
+    console.log(`[CloudServer] Connect from local machine:`);
+    console.log(`  ${connectorCommand}`);
+    this.startHeartbeatCheck();
+    const info = {
+      pid: process.pid,
+      port: this.options.port,
+      path: this.options.path,
+      token,
+      localUrl: localWsUrl,
+      publicUrl: publicWsUrl,
+      connectorCommand,
+      startedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.writeConfigFile(info);
+    return info;
+  }
+  /**
+   * Stand up one HTTP+WebSocket listener. `fromLocal` tags every connection
+   * accepted here so handleRequest can pin command-issuing authority to the
+   * loopback listener.
+   */
+  createListener(port, host, fromLocal) {
+    return new Promise((resolve, reject) => {
+      const httpServer = createHttpServer((req, res) => {
+        console.log(`[CloudServer] HTTP request: ${req.method} ${req.url}`);
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("Not Found - This is a WebSocket server");
+      });
+      const wss = new WebSocketServer({
+        server: httpServer,
+        path: this.options.path,
+        maxPayload: this.options.maxMessageSize
+      });
+      wss.on("connection", (ws, req) => {
+        console.log(
+          `[CloudServer] New ${fromLocal ? "agent" : "connector"} connection from ${req.socket.remoteAddress}, path: ${req.url}`
+        );
+        this.handleConnection(ws, req, fromLocal);
+      });
+      wss.on("error", (error) => {
+        console.error("[CloudServer] WebSocket server error:", error.message);
+      });
+      httpServer.on("error", (error) => {
+        console.error("[CloudServer] HTTP server error:", error.message);
+        reject(error);
+      });
+      if (fromLocal) {
+        this.agentWss = wss;
+        this.agentHttpServer = httpServer;
+      } else {
+        this.connectorWss = wss;
+        this.connectorHttpServer = httpServer;
+      }
+      httpServer.listen(port, host, () => {
+        resolve();
+      });
+    });
+  }
+  stop() {
+    return new Promise((resolve) => {
+      if (this.heartbeatTimer) {
+        clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = null;
+      }
+      for (const [ws] of this.connections) {
+        ws.close();
+      }
+      this.connections.clear();
+      this.pendingRequests.clear();
+      this.agentWss?.close();
+      this.connectorWss?.close();
+      this.agentWss = null;
+      this.connectorWss = null;
+      const servers = [this.agentHttpServer, this.connectorHttpServer].filter(
+        (s) => s !== null
+      );
+      this.agentHttpServer = null;
+      this.connectorHttpServer = null;
+      if (servers.length === 0) {
+        resolve();
+        return;
+      }
+      let remaining = servers.length;
+      for (const s of servers) {
+        s.close(() => {
+          if (--remaining <= 0) resolve();
+        });
+      }
+    });
+  }
+  handleConnection(ws, req, fromLocal) {
+    if (this.connections.size >= this.options.maxConnections) {
+      ws.close(1008, "Server is full");
+      return;
+    }
+    if (this.options.token) {
+      const url = new URL(req.url || "", `http://${req.headers.host}`);
+      const token = url.searchParams.get("token");
+      if (token !== this.options.token) {
+        ws.close(1008, "Unauthorized");
+        return;
+      }
+    }
+    const connId = `${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+    const connection = {
+      ws,
+      id: connId,
+      lastHeartbeat: Date.now(),
+      isAgent: false,
+      fromLocal,
+      messageBuffer: ""
+    };
+    this.connections.set(ws, connection);
+    console.log(`[CloudServer] Client connected: ${connId} (total: ${this.connections.size})`);
+    ws.on("message", (data) => {
+      const conn = this.connections.get(ws);
+      if (!conn) return;
+      conn.messageBuffer += data.toString("utf-8");
+      if (conn.messageBuffer.length > MAX_BUFFER_SIZE) {
+        console.error(
+          `[CloudServer] Message buffer exceeds limit for ${connId}, closing connection`
+        );
+        ws.close(1008, "Message too large");
+        return;
+      }
+      let newlineIndex;
+      while ((newlineIndex = conn.messageBuffer.indexOf("\n")) !== -1) {
+        const line = conn.messageBuffer.slice(0, newlineIndex);
+        conn.messageBuffer = conn.messageBuffer.slice(newlineIndex + 1);
+        if (!line.trim()) continue;
+        try {
+          const message = JSON.parse(line);
+          this.handleMessage(ws, message, connId);
+        } catch (error) {
+          console.error(`[CloudServer] Failed to parse message from ${connId}:`, line, error);
+        }
+      }
+    });
+    ws.on("close", () => {
+      this.connections.delete(ws);
+      this.rejectPendingForWs(ws);
+      console.log(`[CloudServer] Client disconnected: ${connId} (total: ${this.connections.size})`);
+    });
+    ws.on("error", (error) => {
+      console.error(`[CloudServer] Connection error for ${connId}:`, error.message);
+    });
+  }
+  handleMessage(ws, message, connId) {
+    const conn = this.connections.get(ws);
+    if (!conn) return;
+    if (isHeartbeatMessage(message)) {
+      if (message.type === "ping") {
+        ws.send(
+          JSON.stringify({ type: "pong", timestamp: Date.now() }) + "\n"
+        );
+        conn.lastHeartbeat = Date.now();
+      } else if (message.type === "pong") {
+        conn.lastHeartbeat = Date.now();
+      }
+      return;
+    }
+    if (isCloudResponse(message)) {
+      this.handleResponse(ws, message, connId);
+      return;
+    }
+    if (isCloudMessage(message)) {
+      this.handleRequest(ws, message, connId);
+      return;
+    }
+  }
+  handleRequest(ws, message, _connId) {
+    const { id, action, data } = message;
+    const conn = this.connections.get(ws);
+    if (!conn) return;
+    if (!conn.fromLocal && !this.options.allowRemoteAgent) {
+      console.warn(
+        `[CloudServer] Rejected agent request from non-local connection ${conn.id} (action: ${action})`
+      );
+      ws.send(
+        JSON.stringify({
+          id,
+          success: false,
+          error: "Agent requests are only accepted on the local interface (127.0.0.1). Run cloud-client on the same machine as cloud-server, or start the server with --allow-remote-agent to override."
+        }) + "\n"
+      );
+      ws.close(1008, "Agent must be local");
+      return;
+    }
+    conn.isAgent = true;
+    const targetWs = this.findConnector();
+    if (!targetWs) {
+      ws.send(JSON.stringify({ id, success: false, error: "No local connector available" }) + "\n");
+      return;
+    }
+    const requestedTimeoutSec = Number(message.timeoutSec);
+    const timeoutSec = Number.isFinite(requestedTimeoutSec) && requestedTimeoutSec > 0 ? Math.min(requestedTimeoutSec, 3600) : resolveActionTimeoutSec(action, data, this.options.requestTimeout);
+    const timer = setTimeout(
+      () => {
+        this.pendingRequests.delete(id);
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.send(JSON.stringify({ id, success: false, error: "Request timeout" }) + "\n");
+        }
+      },
+      timeoutSec * 1e3 + RESPONSE_GRACE_MS
+    );
+    this.pendingRequests.set(id, { ws, timer });
+    targetWs.send(
+      JSON.stringify({ id, action, data, browser: message.browser, timeoutSec }) + "\n"
+    );
+  }
+  handleResponse(ws, response, _connId) {
+    const conn = this.connections.get(ws);
+    if (!conn) return;
+    if (conn.isAgent) return;
+    const pending = this.pendingRequests.get(response.id);
+    if (!pending) return;
+    this.pendingRequests.delete(response.id);
+    clearTimeout(pending.timer);
+    if (pending.ws.readyState === WebSocket.OPEN) {
+      pending.ws.send(JSON.stringify(response) + "\n");
+    }
+  }
+  findConnector() {
+    for (const [ws, conn] of this.connections) {
+      if (!conn.isAgent && ws.readyState === WebSocket.OPEN) {
+        return ws;
+      }
+    }
+    return null;
+  }
+  rejectPendingForWs(ws) {
+    this.pendingRequests.forEach((pending, id) => {
+      if (pending.ws === ws) {
+        clearTimeout(pending.timer);
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.send(JSON.stringify({ id, success: false, error: "Connection closed" }) + "\n");
+        }
+        this.pendingRequests.delete(id);
+      }
+    });
+  }
+  startHeartbeatCheck() {
+    if (this.heartbeatTimer) return;
+    this.heartbeatTimer = setInterval(() => {
+      const now = Date.now();
+      const timeoutMs = this.options.heartbeatTimeout * 1e3;
+      for (const [ws, conn] of this.connections) {
+        if (now - conn.lastHeartbeat > timeoutMs) {
+          console.log(`[CloudServer] Client ${conn.id} heartbeat timeout, closing connection`);
+          ws.close(1e3, "Heartbeat timeout");
+        }
+      }
+    }, 3e4);
+  }
+  getPublicIP() {
+    const interfaces = networkInterfaces();
+    for (const name of Object.keys(interfaces)) {
+      const iface = interfaces[name];
+      if (!iface) continue;
+      for (const addr of iface) {
+        if (addr.family === "IPv4" && !addr.internal) {
+          return addr.address;
+        }
+      }
+    }
+    return "localhost";
+  }
+  async getSandboxPublicUrl(port) {
+    if (!process.env.AONE_SANDBOX_ID) {
+      return null;
+    }
+    const mappingApiUrl = "http://localhost:58596/api/port-mapping";
+    try {
+      const fetch = await getFetch();
+      const response = await fetch(`${mappingApiUrl}?port=${port}`);
+      if (!response.ok) {
+        return null;
+      }
+      const data = await response.json();
+      if (data.success && data.url) {
+        return data.url;
+      }
+    } catch (error) {
+      console.error(
+        `[CloudServer] Failed to query sandbox port mapping:`,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+    return null;
+  }
+  writeConfigFile(info) {
+    try {
+      if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+      }
+      const config = { server: info.localUrl, ...info };
+      writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
+      console.log(`[CloudServer] Config written to: ${CONFIG_FILE}`);
+    } catch (error) {
+      console.error("[CloudServer] Failed to write config file:", error);
+    }
+  }
+  getStats() {
+    let agents = 0;
+    let connectors = 0;
+    for (const conn of this.connections.values()) {
+      if (conn.isAgent) agents++;
+      else connectors++;
+    }
+    return {
+      connections: this.connections.size,
+      agents,
+      connectors,
+      pendingRequests: this.pendingRequests.size
+    };
+  }
+};
+export {
+  CloudServer
+};

package/dist/paths.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Directory holding cloud-server runtime files (config / log). Shares the single
+ * `~/.mearl` root (resolved cross-platform via `homedir()`) that
+ * daemon-core derives every other daemon path from.
+ */
+export declare const CONFIG_DIR: string;
+/**
+ * Connection config written by the running server and read by cloud-client.
+ * Keeps the `server` field for backward compatibility; daemon lifecycle
+ * commands additionally read `pid` / `port` / `startedAt` from here.
+ */
+export declare const CONFIG_FILE: string;
+/** Daemon stdout/stderr log file. */
+export declare const LOG_FILE: string;

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@mearl/cloud-server",
+  "version": "2.0.0",
+  "description": "Cloud WebSocket server for Mearl — bridges cloud agents to local connectors",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "mearl-cloud-server": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mearl",
+    "cloud-server",
+    "websocket"
+  ],
+  "license": "ISC",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "node-fetch": "^3.3.2",
+    "ws": "^8.18.0",
+    "@mearl/client": "2.0.0",
+    "@mearl/cloud-types": "2.0.0",
+    "@mearl/daemon-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.9.1",
+    "@types/ws": "^8.5.13",
+    "esbuild": "^0.25.2",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "rm -rf dist/ && node build.mjs",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}