@mearl/cloud-server 2.7.0 → 2.7.2

package/README.md

@@ -10,6 +10,12 @@
 npx @mearl/setup --cloud
 ```
 
+Qoder Cloud Agent 使用同一套包和 server 命令，只在 setup 时选择配对模式：
+
+```bash
+npx @mearl/setup --qoder-cloud --yes
+```
+
 在 Docker 或自定义进程托管等只需要 Server 包的场景，可单独安装 `@mearl/cloud-server`。
 
 ## 使用
@@ -17,6 +23,8 @@ npx @mearl/setup --cloud
 ### 命令行方式
 
 Server **默认以后台守护进程方式运行**，启动后立即返回，并打印本地机器需要执行的连接命令。
+Qoder 模式保持相同的 `start/status/restart/stop/logs` 交互；`start` 和 `restart` 生成新的
+pair/connector 信息后退出，不监听端口或创建守护进程。
 
 ```bash
 mearl-cloud-server [command] [options]
@@ -66,12 +74,13 @@ mearl-cloud-server --foreground
 [CloudServer] Logs: ~/.mearl/cloud-server.log
 
   Connect from your local machine:
-    npx @mearl/cloud-connector "ws://10.0.1.100:8080/ws?token=xxx"
+    npx @mearl/cloud-connector start "ws://10.0.1.100:8080/ws?token=xxx"
 ```
 
 运行时文件位于 `~/.mearl/`：
 
 - `cloud-server.json` - 连接配置（含 server URL、pid、端口等），统一 `@mearl/client` 自动读取
+- `cloud-server-mode.json` - setup 在 Qoder 模式下写入的标识；普通 `--cloud` 会删除它
 - `cloud-server.log` - 后台进程日志（`logs` 子命令读取，或 `tail -f` 跟踪）；超过 5MB 会在下次启动时滚动为 `cloud-server.log.1`
 
 > 守护进程的启停、状态、日志滚动等生命周期逻辑由共享包 [`@mearl/daemon-core`](../../daemon-core) 提供（与 cloud-connector 复用同一套实现）。
@@ -111,6 +120,10 @@ console.log(stats);
 await server.stop();
 ```
 
+Qoder 模式只复用 cloud-server CLI 作为建联入口。配对完成后的 action 继续通过 Qoder
+Client-Side `mearl` 工具、Session API 和本地 connector 转发，不会连接一个本地
+cloud-server 端口。
+
 ## 架构
 
 ```

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

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

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

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

package/dist/cli.js

@@ -16,6 +16,7 @@ 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 MODE_FILE = join(CONFIG_DIR, "cloud-server-mode.json");
 var LOG_FILE = join(CONFIG_DIR, "cloud-server.log");
 
 // src/index.ts
@@ -109,7 +110,7 @@ var CloudServer = class {
         "[CloudServer] Connector traffic is using unencrypted ws://. Use a TLS-terminating proxy and wss:// when the connection crosses a trusted network."
       );
     }
-    const connectorCommand = `npx @mearl/cloud-connector "${publicWsUrl}"`;
+    const connectorCommand = `npx @mearl/cloud-connector start "${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)`
     );
@@ -433,12 +434,13 @@ var CloudServer = class {
   resolveConnector(selector) {
     const connectors = this.getConnectorConnections();
     if (connectors.length === 0) return { error: "No local connector available" };
+    const available = connectors.map(({ info }) => `${info.name} [${info.connectorId}]`).join(", ");
     if (!selector) {
       if (connectors.length === 1) {
         return { ws: connectors[0].ws, info: connectors[0].info };
       }
       return {
-        error: `Multiple cloud connectors are connected (${connectors.length}). Run \`mearl connector_list\` and pass --connector <id|name>.`
+        error: `Multiple cloud connectors are connected (${connectors.length}). Pass --connector <id|name>. Available: ${available}`
       };
     }
     const selection = resolveCloudConnectorSelector(
@@ -449,7 +451,6 @@ var CloudServer = class {
       const matched = connectors.find(({ info }) => info === selection.connector);
       return { ws: matched.ws, info: matched.info };
     }
-    const available = connectors.map(({ info }) => `${info.name} [${info.connectorId}]`).join(", ");
     if (selection.status === "ambiguous") {
       return {
         error: `Cloud connector selector "${selector}" is ambiguous. Available: ${available}`
@@ -563,7 +564,7 @@ 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);
+  const command2 = config.publicUrl ? `npx @mearl/cloud-connector start "${config.publicUrl}"` : config.connectorCommand;
   if (command2) {
     lines.push("");
     lines.push("  Connect from your local machine:");
@@ -581,6 +582,9 @@ function daemon(foregroundArgs) {
     formatInfo: formatConnectInfo
   });
 }
+function isDaemonRunning() {
+  return daemon([]).running() !== null;
+}
 function startDaemon(passthroughArgs) {
   return daemon(passthroughArgs).start();
 }
@@ -619,8 +623,107 @@ async function runForeground(options) {
   process.on("SIGTERM", () => void shutdown("SIGTERM"));
 }
 
+// src/mode.ts
+import { mkdirSync as mkdirSync2, readFileSync, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname } from "node:path";
+var CLOUD_SERVER_MODE_ENV = "MEARL_CLOUD_MODE";
+function isCloudServerMode(value) {
+  return value === "websocket" || value === "qoder";
+}
+function readStoredMode(storage) {
+  const modeFile = storage.modeFile ?? MODE_FILE;
+  const readText = storage.readText ?? ((filePath) => readFileSync(filePath, "utf8"));
+  try {
+    const value = JSON.parse(readText(modeFile));
+    return isCloudServerMode(value.mode) ? value.mode : null;
+  } catch {
+    return null;
+  }
+}
+function writeStoredMode(mode, storage) {
+  const modeFile = storage.modeFile ?? MODE_FILE;
+  const writeText = storage.writeText ?? ((filePath, value) => {
+    mkdirSync2(dirname(filePath), { recursive: true });
+    writeFileSync2(filePath, value, { encoding: "utf8", mode: 384 });
+  });
+  writeText(modeFile, `${JSON.stringify({ mode })}
+`);
+}
+function clearStoredMode(storage) {
+  const modeFile = storage.modeFile ?? MODE_FILE;
+  const removeFile = storage.removeFile ?? ((filePath) => rmSync(filePath, { force: true }));
+  removeFile(modeFile);
+}
+function resolveCloudServerMode(env = process.env, storage = {}) {
+  const requested = env[CLOUD_SERVER_MODE_ENV];
+  if (requested !== void 0) {
+    if (!isCloudServerMode(requested)) {
+      throw new Error(`${CLOUD_SERVER_MODE_ENV} must be "websocket" or "qoder"`);
+    }
+    if (requested === "qoder") writeStoredMode(requested, storage);
+    else clearStoredMode(storage);
+    return requested;
+  }
+  return readStoredMode(storage) ?? "websocket";
+}
+
+// src/qoder.ts
+import { randomBytes as randomBytes2 } from "node:crypto";
+function createQoderPairingInfo(options = {}) {
+  const pairingCode = (options.createCode ?? (() => randomBytes2(24).toString("base64url")))();
+  if (!/^[A-Za-z0-9_-]{16,128}$/.test(pairingCode)) {
+    throw new Error("Qoder pairing code must be 16-128 URL-safe characters");
+  }
+  const createdAt = (options.now ?? Date.now)();
+  if (!Number.isSafeInteger(createdAt) || createdAt < 1e12 || createdAt > 9999999999999) {
+    throw new Error("Qoder pairing timestamp must be a 13-digit epoch millisecond value");
+  }
+  return {
+    pairingCode,
+    createdAt,
+    connectorUrl: `qoder://pair/${pairingCode}?created=${createdAt}`,
+    toolInput: { action: "pair", payload: { code: pairingCode } }
+  };
+}
+function formatQoderPairingOutput(info) {
+  const connectorCommand = `npx @mearl/cloud-connector start "${info.connectorUrl}"`;
+  return `[CloudServer] Qoder pairing mode is ready.
+
+  Connect from your local machine:
+    ${connectorCommand}
+
+  Then immediately invoke the Qoder client-side custom tool named "mearl" with this input:
+    ${JSON.stringify(info.toolInput)}
+
+The connector resolves QODER_PERSONAL_ACCESS_TOKEN from the local environment, ~/.mearl/.env, or supported local credential storage. Never add the PAT to the pairing URL.`;
+}
+async function runQoderCloudServerCommand(command2, dependencies) {
+  const writeLine = dependencies.writeLine ?? console.log;
+  switch (command2) {
+    case "start":
+    case "restart":
+      if (dependencies.isServerRunning()) await dependencies.stopServer();
+      writeLine(
+        formatQoderPairingOutput(
+          (dependencies.createPairing ?? (() => createQoderPairingInfo()))()
+        )
+      );
+      break;
+    case "status":
+      dependencies.printStatus();
+      writeLine("[CloudServer] Mode: qoder pairing (no listening service)");
+      break;
+    case "stop":
+      await dependencies.stopServer();
+      break;
+    case "logs":
+      dependencies.printLogs();
+      break;
+  }
+}
+
 // src/cli.ts
-var CLOUD_SERVER_VERSION = true ? "2.7.0" : "unknown";
+var CLOUD_SERVER_VERSION = true ? "2.7.2" : "unknown";
 var argv = process.argv.slice(2);
 if (argv.includes("--version") || argv.includes("-v")) {
   console.log(CLOUD_SERVER_VERSION);
@@ -712,6 +815,16 @@ function parseOptions(args) {
   return options;
 }
 async function main() {
+  const mode = resolveCloudServerMode();
+  if (mode === "qoder") {
+    await runQoderCloudServerCommand(command, {
+      isServerRunning: isDaemonRunning,
+      stopServer: stopDaemon,
+      printStatus: statusDaemon,
+      printLogs
+    });
+    return;
+  }
   if (foreground) {
     await runForeground(parseOptions(rest));
     return;

package/dist/daemon.d.ts

@@ -1,4 +1,6 @@
 import { CloudServerOptions } from './index.js';
+/** Whether a live WebSocket daemon exists, independent from the selected transport mode. */
+export declare function isDaemonRunning(): boolean;
 /** Spawn the server as a detached background process. */
 export declare function startDaemon(passthroughArgs: string[]): Promise<void>;
 /** Stop a running background server. */

package/dist/index.js

@@ -10,6 +10,7 @@ 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 MODE_FILE = join(CONFIG_DIR, "cloud-server-mode.json");
 var LOG_FILE = join(CONFIG_DIR, "cloud-server.log");
 
 // src/index.ts
@@ -103,7 +104,7 @@ var CloudServer = class {
         "[CloudServer] Connector traffic is using unencrypted ws://. Use a TLS-terminating proxy and wss:// when the connection crosses a trusted network."
       );
     }
-    const connectorCommand = `npx @mearl/cloud-connector "${publicWsUrl}"`;
+    const connectorCommand = `npx @mearl/cloud-connector start "${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)`
     );
@@ -427,12 +428,13 @@ var CloudServer = class {
   resolveConnector(selector) {
     const connectors = this.getConnectorConnections();
     if (connectors.length === 0) return { error: "No local connector available" };
+    const available = connectors.map(({ info }) => `${info.name} [${info.connectorId}]`).join(", ");
     if (!selector) {
       if (connectors.length === 1) {
         return { ws: connectors[0].ws, info: connectors[0].info };
       }
       return {
-        error: `Multiple cloud connectors are connected (${connectors.length}). Run \`mearl connector_list\` and pass --connector <id|name>.`
+        error: `Multiple cloud connectors are connected (${connectors.length}). Pass --connector <id|name>. Available: ${available}`
       };
     }
     const selection = resolveCloudConnectorSelector(
@@ -443,7 +445,6 @@ var CloudServer = class {
       const matched = connectors.find(({ info }) => info === selection.connector);
       return { ws: matched.ws, info: matched.info };
     }
-    const available = connectors.map(({ info }) => `${info.name} [${info.connectorId}]`).join(", ");
     if (selection.status === "ambiguous") {
       return {
         error: `Cloud connector selector "${selector}" is ambiguous. Available: ${available}`

package/dist/mode.d.ts

@@ -0,0 +1,10 @@
+export type CloudServerMode = 'websocket' | 'qoder';
+export declare const CLOUD_SERVER_MODE_ENV = "MEARL_CLOUD_MODE";
+interface CloudServerModeStorage {
+    modeFile?: string;
+    readText?: (filePath: string) => string;
+    removeFile?: (filePath: string) => void;
+    writeText?: (filePath: string, value: string) => void;
+}
+export declare function resolveCloudServerMode(env?: NodeJS.ProcessEnv, storage?: CloudServerModeStorage): CloudServerMode;
+export {};

package/dist/paths.d.ts

@@ -9,5 +9,7 @@ export declare const CONFIG_DIR: string;
  * Daemon lifecycle commands additionally read `pid` / `port` / `startedAt`.
  */
 export declare const CONFIG_FILE: string;
+/** Persistent transport mode selected by setup; independent from daemon liveness. */
+export declare const MODE_FILE: string;
 /** Daemon stdout/stderr log file. */
 export declare const LOG_FILE: string;

package/dist/qoder.d.ts

@@ -0,0 +1,29 @@
+export interface QoderPairingInfo {
+    pairingCode: string;
+    createdAt: number;
+    connectorUrl: string;
+    toolInput: {
+        action: 'pair';
+        payload: {
+            code: string;
+        };
+    };
+}
+export interface QoderPairingOptions {
+    now?: () => number;
+    createCode?: () => string;
+}
+export type CloudServerCommand = 'start' | 'stop' | 'restart' | 'status' | 'logs';
+interface QoderCloudServerDependencies {
+    createPairing?: () => QoderPairingInfo;
+    isServerRunning: () => boolean;
+    printLogs: () => void;
+    printStatus: () => void;
+    stopServer: () => Promise<void>;
+    writeLine?: (message: string) => void;
+}
+/** Create a short-lived correlation handle without embedding Qoder credentials in the URL. */
+export declare function createQoderPairingInfo(options?: QoderPairingOptions): QoderPairingInfo;
+export declare function formatQoderPairingOutput(info: QoderPairingInfo): string;
+export declare function runQoderCloudServerCommand(command: CloudServerCommand, dependencies: QoderCloudServerDependencies): Promise<void>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/cloud-server",
-  "version": "2.7.0",
+  "version": "2.7.2",
   "description": "Cloud WebSocket server for Mearl — bridges cloud agents to local connectors",
   "type": "module",
   "main": "dist/index.js",
@@ -29,9 +29,9 @@
   "dependencies": {
     "node-fetch": "^3.3.2",
     "ws": "^8.18.0",
-    "@mearl/cloud-types": "2.7.0",
-    "@mearl/client": "2.7.0",
-    "@mearl/daemon-core": "2.7.0"
+    "@mearl/daemon-core": "2.7.2",
+    "@mearl/client": "2.7.2",
+    "@mearl/cloud-types": "2.7.2"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",