@co0ontty/wand 4.72.2-beta.gcc5d57e → 4.73.0

package/dist/render-binary.js

@@ -0,0 +1,204 @@
+import { accessSync, constants, existsSync, readFileSync, statSync } from "node:fs";
+import { execFile, spawnSync } from "node:child_process";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+/** 仓库根：src/ 与 dist/ 都在根下一层，所以两种运行方式解析结果一致。 */
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const VERSION_PROBE_TIMEOUT_MS = 2_000;
+const ARCH_PROBE_TIMEOUT_MS = 1_000;
+/**
+ * 支持的分发三元组。
+ *
+ * 与 `render-bin/manifest.json` 的版本条目键、`render/release.json` 的
+ * `supportedTriples` 必须一致；新增平台要同时改这三处与 CI 矩阵。
+ */
+export const SUPPORTED_RENDER_TRIPLES = ["darwin-arm64", "darwin-x64", "linux-x64", "linux-arm64"];
+/** `uname -m` 的架构别名 → Node 的 `process.arch` 命名（两个生态叫法不同）。 */
+const MACHINE_ARCH_ALIASES = {
+    arm64: "arm64",
+    aarch64: "arm64",
+    x86_64: "x64",
+    amd64: "x64",
+    x64: "x64",
+};
+/** `uname -m` 的输出归一成 Node 的 arch 名；认不出返回 null（调用方回退 process.arch）。 */
+export function normalizeMachineArch(machine) {
+    if (typeof machine !== "string")
+        return null;
+    return MACHINE_ARCH_ALIASES[machine.trim().toLowerCase()] ?? null;
+}
+/**
+ * 平台三元组（`darwin-arm64` 等）。
+ *
+ * 为什么不直接用 `process.arch`：macOS 上 Node 跑在 Rosetta 里时它报 `x64`，
+ * 而机器其实是 arm64 —— 于是会去找一个不存在（或架构不符）的产物，最后表现成
+ * 「自动模式下 Rust 引擎莫名其妙不生效」。`uname -m` 才反映真实硬件；只有
+ * `uname` 不可用（PATH 被清空、Windows）时才回退 `process.arch`。
+ *
+ * `rosettaTranslated` 是反向兜底：翻译态下 `uname -m` 同样报 `x86_64`，
+ * 只有 `sysctl.proc_translated` 能说明「这个 x64 进程跑在 arm64 机器上」。
+ * 少了它，上面那条规则在它最该生效的场景里形同虚设。
+ */
+export function resolveRenderTriple(platform, nodeArch, unameMachine, rosettaTranslated = false) {
+    let arch = normalizeMachineArch(unameMachine) ?? nodeArch;
+    if (platform === "darwin" && arch === "x64" && rosettaTranslated)
+        arch = "arm64";
+    return `${platform}-${arch}`;
+}
+let cachedPlatformArchProbe = null;
+/**
+ * 真实架构探测（进程级缓存）：`resolveRenderBinaryPath` 在一次启动里会被调用多次，
+ * 不该每次都 spawn 两个进程。
+ */
+export function probePlatformArch() {
+    if (!cachedPlatformArchProbe) {
+        cachedPlatformArchProbe = {
+            unameMachine: runUnameMachine(),
+            rosettaTranslated: isRosettaTranslated(),
+        };
+    }
+    return cachedPlatformArchProbe;
+}
+/** 当前进程应使用的三元组。 */
+export function currentRenderTriple() {
+    const probe = probePlatformArch();
+    return resolveRenderTriple(process.platform, process.arch, probe.unameMachine, probe.rosettaTranslated);
+}
+function runUnameMachine() {
+    if (process.platform === "win32")
+        return null;
+    try {
+        const result = spawnSync("uname", ["-m"], {
+            encoding: "utf8",
+            timeout: ARCH_PROBE_TIMEOUT_MS,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        if (result.error || result.status !== 0)
+            return null;
+        return (result.stdout ?? "").trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `sysctl.proc_translated` == 1 表示当前进程被 Rosetta 翻译（只在 darwin 上有意义）。 */
+function isRosettaTranslated() {
+    if (process.platform !== "darwin")
+        return false;
+    try {
+        const result = spawnSync("sysctl", ["-n", "sysctl.proc_translated"], {
+            encoding: "utf8",
+            timeout: ARCH_PROBE_TIMEOUT_MS,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        if (result.error || result.status !== 0)
+            return false;
+        return (result.stdout ?? "").trim() === "1";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 约定候选路径（不含 `WAND_RENDER_BIN` 与 `PATH`，调用方单独处理）。
+ *
+ * 顺序刻意把「刚 cargo build 出来的」排在分发位置之前：开发机上调 Rust 引擎时
+ * 期望立刻生效，而不是被上一次安装的旧二进制盖住。
+ *
+ * 旧布局（`wand-rs/`、仓库根 `native/`）已不存在，候选里不留兼容分支：
+ * 留着只会让「引擎没生效」这类问题多一个静默的假来源。
+ */
+export function renderBinaryCandidates(configDir, triple) {
+    const binaryName = process.platform === "win32" ? "wand-render.exe" : "wand-render";
+    return [
+        path.join(REPO_ROOT, "render", "target", "release", binaryName),
+        path.join(REPO_ROOT, "render", "target", "debug", binaryName),
+        path.join(configDir, "bin", binaryName),
+        // npm 包内嵌的正式位置：scripts/stage-render-binaries.js 把 render-bin 的产物写在这里，
+        // dist/ 在 package.json 的 files 里，所以全局安装后也有二进制。
+        path.join(REPO_ROOT, "dist", "native", triple, binaryName),
+    ];
+}
+/**
+ * 解析 wand-render 可执行文件。
+ *
+ * 顺序：`WAND_RENDER_BIN` → `<repo>/render/target/{release,debug}` → `<configDir>/bin`
+ * → `<repo>/dist/native/<triple>` → `PATH`。返回 null 表示「这台机器没有」，由调用方
+ * 按 engine 决定告警还是报错。
+ */
+export function resolveRenderBinaryPath(configPath) {
+    const binaryName = process.platform === "win32" ? "wand-render.exe" : "wand-render";
+    const fromEnv = process.env.WAND_RENDER_BIN?.trim();
+    if (fromEnv) {
+        if (isExecutableFile(fromEnv))
+            return fromEnv;
+        // 显式配置但不存在属于配置错误，必须可见，不能静默滑到仓库构建产物。
+        process.stderr.write(`[wand] WAND_RENDER_BIN points at ${fromEnv}, which is not an executable file; falling back to discovery.\n`);
+    }
+    const configDir = path.dirname(path.resolve(configPath));
+    const triple = currentRenderTriple();
+    for (const candidate of renderBinaryCandidates(configDir, triple)) {
+        if (isExecutableFile(candidate))
+            return candidate;
+    }
+    for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = path.join(dir, binaryName);
+        if (isExecutableFile(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * 读取 wand-render 的版本。
+ *
+ * 先读二进制旁边的 `wand-render.version` sidecar（就位脚本会写），读不到才去跑
+ * `wand-render --version` —— 启动路径上不该无谓地执行一个进程。
+ * 两种方式都失败时返回 null：调用方只要一个展示用版本号，拿不到不能影响启动。
+ */
+export function readRenderBinaryVersion(binaryPath) {
+    const sidecar = readVersionSidecar(binaryPath);
+    if (sidecar)
+        return Promise.resolve(sidecar);
+    return new Promise((resolve) => {
+        execFile(binaryPath, ["--version"], { timeout: VERSION_PROBE_TIMEOUT_MS }, (error, stdout) => {
+            if (error) {
+                resolve(null);
+                return;
+            }
+            const firstLine = stdout.split("\n").map((line) => line.trim()).find((line) => line.length > 0) ?? "";
+            const version = /(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.]+)?)/.exec(firstLine);
+            resolve(version ? version[1] : null);
+        });
+    });
+}
+function readVersionSidecar(binaryPath) {
+    try {
+        const raw = readFileSync(path.join(path.dirname(binaryPath), "wand-render.version"), "utf8").trim();
+        const version = /^(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.]+)?)$/.exec(raw);
+        return version ? version[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function isExecutableFile(candidate) {
+    try {
+        if (!existsSync(candidate) || !statSync(candidate).isFile())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    if (process.platform === "win32")
+        return true;
+    try {
+        accessSync(candidate, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/render-daemon-client.d.ts

@@ -0,0 +1,171 @@
+import { type RenderMethod } from "./render-protocol.js";
+import { type TerminalAttachResult, type TerminalHost, type TerminalSessionState, type TerminalSpawnRequest } from "./terminal-host.js";
+/**
+ * 鉴权层面的失败（与网络抖动区分）。
+ *
+ * 特征：连接建立成功、hello 发出后对端**一个字节都没回**就关闭 —— Render 对
+ * token 不符/协议不符的处理就是直接 `close()`。单独一个类型是为了让重连策略
+ * 能把「同一把废 token」和「daemon 不在了」区分开，而不是一律 10s 重试。
+ */
+export declare class RenderAuthError extends Error {
+    constructor(message: string);
+}
+/**
+ * Render（常驻 PTY 持有者）的 Node 客户端。
+ *
+ * 与 legacy `TerminalDaemonClient` 的关键差异：**这里只有 PTY**，没有结构化运行；
+ * 另外 `disconnect()` 只解绑 socket，Render 进程与其 PTY 全部保留 —— 这正是
+ * Server 因 `npm update` 重启而 PTY 不丢的前提。
+ */
+export declare class RenderDaemonClient implements TerminalHost {
+    private readonly socketPath;
+    private readonly token;
+    /**
+     * token 文件路径。给了它就在**每次 connect 时重读**：Render 崩溃/升级重启后
+     * 会 `generate_token()` 轮换 token，只缓存构造期的那一把会让重连永远鉴权失败
+     * （现象是 `createOrAttach` 全部失败、错误只显示 unavailable，旧会话被永久报成 running）。
+     */
+    private readonly tokenPath;
+    /** Persisted PTY IDs used only if v1 `list` exceeds its aggregate frame limit. */
+    private readonly knownSessionIds;
+    readonly persistent = true;
+    private socket;
+    private nextRequestId;
+    private readonly pending;
+    private readonly inventory;
+    private readonly handles;
+    private readonly pendingEvents;
+    private readonly pendingEventOverflows;
+    private readonly refreshingSessions;
+    private reconciling;
+    private eventsDuringReconcile;
+    private reconcileDuringSync;
+    private headerParts;
+    private headerBytes;
+    private bodyParts;
+    private bodyBytes;
+    private frameLength;
+    private disposed;
+    private reconnectTimer;
+    private reconnectDelayMs;
+    private reconnectFailureLogged;
+    private offlineOperationLogged;
+    /** 协议版本不匹配是终态：重试无意义，也不允许降级运行。 */
+    private fatalProtocolError;
+    private daemonVersion;
+    /** 最近一次 connect 时实际使用的凭据。 */
+    private activeToken;
+    /** 最后一次成功读到的凭据；token 文件暂时读不到时用它，避免重连因一次 IO 失败直接放弃。 */
+    private lastKnownToken;
+    /** 已经因为「读不到 token 文件」告警过，避免每次重连都刷一行。 */
+    private tokenReadFailureLogged;
+    /** 当前 socket 上已解出的帧数，用来区分「未鉴权被直接关闭」与网络错误。 */
+    private framesOnCurrentSocket;
+    private connecting;
+    private stopHeartbeat;
+    constructor(socketPath: string, token: string, 
+    /**
+     * token 文件路径。给了它就在**每次 connect 时重读**：Render 崩溃/升级重启后
+     * 会 `generate_token()` 轮换 token，只缓存构造期的那一把会让重连永远鉴权失败
+     * （现象是 `createOrAttach` 全部失败、错误只显示 unavailable，旧会话被永久报成 running）。
+     */
+    tokenPath?: string | null, 
+    /** Persisted PTY IDs used only if v1 `list` exceeds its aggregate frame limit. */
+    knownSessionIds?: readonly string[]);
+    get version(): string;
+    connect(): Promise<void>;
+    private open;
+    /**
+     * 对端一个字节都没回就断开：daemon 对 token/协议不符的处理是直接 `close()`
+     * （`wand-renderd` 的 `server.rs`），所以这是鉴权/版本问题的特征，不是网络抖动。
+     * 归类为 `RenderAuthError`，由重连策略决定「别再 10s 一次拿同一把废 token 试」。
+     */
+    private describeConnectFailure;
+    /**
+     * 读取当前凭据：每次都用 token 文件里的**最新**值（daemon 重启会轮换）。
+     * 文件暂时读不到（渲染器正在退出、路径还没建）不是致命错误，回落到上一次成功
+     * 读到的值并告警一次；下一次连接会重试读文件。
+     */
+    private readToken;
+    private warnTokenFileUnusable;
+    /** resize 走的是异步 RPC，但 inventory 必须立刻反映新尺寸（见 RemoteRenderProcess.resize）。 */
+    noteTerminalResize(sessionId: string, cols: number, rows: number): void;
+    attach(sessionId: string, afterSeq?: number): TerminalAttachResult | null;
+    createOrAttach(request: TerminalSpawnRequest, afterSeq?: number): Promise<TerminalAttachResult>;
+    forget(sessionId: string): void;
+    /**
+     * 只解绑：关闭 socket、清掉内存句柄，**Render 进程与它的所有 PTY 都保持运行**。
+     * 这是 Server / Render 分离的核心 —— 下一次启动 attach 回来仍拿到同一批会话。
+     */
+    disconnect(): void;
+    /**
+     * Best-effort 操作：Render 不可用时打 stderr，绝不把异常抛回调用方，
+     * 否则一次 PTY 抖动会顺着 ProcessManager 把整个会话路径打断。
+     */
+    fireOperation(sessionId: string, method: RenderMethod, params?: Record<string, unknown>): void;
+    confirmWrite(sessionId: string, data: string): Promise<void>;
+    reportOperationError(sessionId: string, method: RenderMethod, error: unknown): void;
+    private listSessions;
+    /** `list` locates sessions; each `attach` is the authoritative recovery state. */
+    private loadAuthoritativeSessions;
+    private parseHello;
+    private request;
+    private consume;
+    private resetFrameDecoder;
+    private handleFrame;
+    private handleResponse;
+    private routeEvent;
+    private queuePendingEvent;
+    /** Repair a bounded event-buffer overflow without replaying a partial stream. */
+    private refreshSession;
+    /**
+     * Render 主动告知当前会话集合（例如自身清掉了已 forget 的会话）。不在
+     * 集合里的会话要给既有句柄补一个退出事件，否则 ProcessManager 会永远停在 running。
+     */
+    private handleReconcileEvent;
+    /**
+     * Socket 断开后的重连。不做重连的话，Render 重启一次所有
+     * RemoteRenderProcess 就会静默失效，而 ProcessManager 仍显示 running。
+     */
+    private handleDisconnect;
+    /** 被同一个凭据反复拒绝时置位：下一次重连改用长退避（见 `scheduleReconnect`）。 */
+    private authBackoff;
+    /**
+     * 安排下一次重连（已有定时器时不重排：一次失败可能会从 close/error 两条路径
+     * 各调一次，重排会把退避倍率叠成指数增长）。需要**覆盖**已有定时器的场景
+     * （鉴权失败要把 10s 换成 60s）由调用方显式清掉再调。
+     */
+    private scheduleReconnect;
+    private tryReconnect;
+    /**
+     * 重连失败的日志与「同一把废 token」判定。
+     *
+     * 判定依据：刚刚用掉的那把凭据（`activeToken`，每次连接开头从 token 文件重读）
+     * 与文件里**现在**这一把相同 → 再试同一个值不可能成功（对端持有的是别的 token，
+     * 多来自 `-c` 指到了另一个 config 或有人在手工改 token 文件），摆成 60s 长退避。
+     * 文件已经变了就按普通退避重试 —— 那正是 daemon 重启轮换 token 后的自愈路径。
+     * @returns 是否处于「同一把废凭据」状态（调用方据此换长退避）
+     */
+    private noteReconnectFailure;
+    /** 只读 token 文件当前值（不改状态）；读不到返回 null。 */
+    private currentTokenFileValue;
+    /**
+     * 断线期间 Render 可能新建/结束会话。用断线前的 inventory 与新的 `list` 对账：
+     * 活着的补发缺口 chunk；消失或已退出的给句柄补合成退出。
+     */
+    private reconcileAfterReconnect;
+    private resultFromState;
+    private rejectPending;
+}
+/**
+ * 运行期校验 Render 的 SessionState。
+ *
+ * 协议是跨语言契约（Rust 侧字段名漂移过一次就是静默的空终端），所以这里不做
+ * 结构断言直接使用，而是逐字段检查：能修的补默认值，修不了的整条丢弃并打警告。
+ */
+export declare function normalizeRenderSessionState(value: unknown): TerminalSessionState | null;
+/**
+ * 连接一个已经存在的 Render（socket + token 都在）。**不 spawn**，找不到就返回 null，
+ * 这样调用方可以区分「已被别处 adopt」和「需要自己拉起」。
+ */
+export declare function connectExistingRenderClient(configPath: string, knownSessionIds?: readonly string[]): Promise<RenderDaemonClient | null>;