@ycodium-ai/plugin-devices 0.0.0-stage → 0.2.2808

package/dist/helper.mjs

@@ -0,0 +1,286 @@
+// 设备插件的子进程助手：由插件经 `ctx.process` 以 `host:node helper.mjs <模式> …` 起，
+// 跑在服务器自己的 Node 上（桌面版是带 ELECTRON_RUN_AS_NODE 的 Electron）。
+//
+// 宿主不许插件给子进程改 PATH，而 hub 在 Windows 上只靠 PATH 找模拟器、agent-device 的守护进程
+// 也要 adb，npm 的安装脚本要在 PATH 上找 node。所以这几类子进程都经这里：在这个进程里补好 PATH，
+// 再在同一进程里装载目标脚本（`node`、`npm` 模式）或起目标程序（`run` 模式）。插件停用时宿主杀的
+// 是这个进程，装载进来的目标脚本也就跟着没了。
+//
+// 只用 node 内置模块；输出给插件解析的一律是单行 JSON。
+//
+// 它不是插件进程里的代码，而是插件经 `ctx.process` 起的独立程序，跟插件自带的二进制同一类，
+// 所以放在 `bin/` 而不是 `src/`：插件源码边界（不许直接起子进程）管的是 `src/`。`run` 模式自己
+// 起 adb / emulator，并把 SIGTERM / SIGINT 转给它；Windows 上宿主直接结束本进程，收不到信号。
+import * as NodeChildProcess from "node:child_process";
+import * as NodeFS from "node:fs";
+import * as NodePath from "node:path";
+import * as NodeURL from "node:url";
+import * as NodeZlib from "node:zlib";
+
+// oxlint-disable-next-line ycodium/no-global-process-runtime -- 独立子进程脚本，没有 Effect 运行时可注入。
+const hostPlatform = process.platform;
+const isWindows = hostPlatform === "win32";
+const exe = (name) => (isWindows ? `${name}.exe` : name);
+
+/** `--sdk x --shim y -- rest…`：选项在 `--` 之前，其余原样交给目标。其它环境变量由插件经 spawn 的 env 给。 */
+function parseArgs(argv) {
+  const options = { sdk: null, shim: null, rest: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === "--") {
+      options.rest = argv.slice(index + 1);
+      break;
+    }
+    if (value === "--sdk" || value === "--shim") {
+      options[value.slice(2)] = argv[index + 1] || null;
+      index += 1;
+    }
+  }
+  return options;
+}
+
+function prependPath(directories) {
+  const key = Object.keys(process.env).find((name) => name.toUpperCase() === "PATH") ?? "PATH";
+  process.env[key] = [...directories, process.env[key] ?? ""]
+    .filter(Boolean)
+    .join(NodePath.delimiter);
+}
+
+/**
+ * 在 `directory` 里放一个叫 node 的垫片，指向跑这个助手的可执行文件。npm 的安装脚本
+ * （比如原生依赖的预编译下载器）按名字在 PATH 上找 node，而这台机器的 PATH 上可能根本没有。
+ * ELECTRON_RUN_AS_NODE 已经在本进程环境里（宿主起 host:node 时补的），垫片起的进程照样继承。
+ */
+function writeNodeShim(directory) {
+  NodeFS.mkdirSync(directory, { recursive: true });
+  if (isWindows) {
+    NodeFS.writeFileSync(NodePath.join(directory, "node.cmd"), `@"${process.execPath}" %*\r\n`);
+  } else {
+    const file = NodePath.join(directory, "node");
+    NodeFS.writeFileSync(
+      file,
+      `#!/bin/sh\nexec '${process.execPath.replaceAll("'", `'"'"'`)}' "$@"\n`,
+    );
+    NodeFS.chmodSync(file, 0o755);
+  }
+}
+
+/** 读 tar 头里的一个八进制数字段。 */
+function octal(block, start, length) {
+  const text = block
+    .subarray(start, start + length)
+    .toString("utf8")
+    .replaceAll("\0", "")
+    .trim();
+  return text.length === 0 ? 0 : Number.parseInt(text, 8);
+}
+
+function text(block, start, length) {
+  const raw = block.subarray(start, start + length);
+  const end = raw.indexOf(0);
+  return raw.subarray(0, end === -1 ? raw.length : end).toString("utf8");
+}
+
+/** PAX 扩展头里的 `path=`；其余键这里用不到。 */
+function paxPath(body) {
+  let offset = 0;
+  while (offset < body.length) {
+    const space = body.indexOf(0x20, offset);
+    if (space === -1) break;
+    const length = Number.parseInt(body.subarray(offset, space).toString("utf8"), 10);
+    if (!Number.isFinite(length) || length <= 0) break;
+    const record = body.subarray(space + 1, offset + length - 1).toString("utf8");
+    if (record.startsWith("path=")) return record.slice("path=".length);
+    offset += length;
+  }
+  return null;
+}
+
+/**
+ * 解一个 npm 包的 .tgz 到 `destination`，去掉包内统一的第一层目录（npm 包是 `package/`）。
+ * 只认普通文件和目录；条目路径解析后必须仍在 `destination` 内。
+ */
+function extractTarball(file, destination) {
+  const archive = NodeZlib.gunzipSync(NodeFS.readFileSync(file));
+  const root = NodePath.resolve(destination);
+  let offset = 0;
+  let pendingName = null;
+  let count = 0;
+  while (offset + 512 <= archive.length) {
+    const block = archive.subarray(offset, offset + 512);
+    if (block.every((byte) => byte === 0)) break;
+    const size = octal(block, 124, 12);
+    const type = String.fromCharCode(block[156] || 0x30);
+    const bodyStart = offset + 512;
+    const body = archive.subarray(bodyStart, bodyStart + size);
+    offset = bodyStart + Math.ceil(size / 512) * 512;
+    if (type === "x") {
+      pendingName = paxPath(body);
+      continue;
+    }
+    if (type === "L") {
+      pendingName = text(body, 0, body.length);
+      continue;
+    }
+    if (type === "g") continue;
+    const prefix = text(block, 345, 155);
+    const name = pendingName ?? (prefix ? `${prefix}/${text(block, 0, 100)}` : text(block, 0, 100));
+    pendingName = null;
+    const relative = name.split("/").slice(1).join("/");
+    if (relative.length === 0) continue;
+    const target = NodePath.resolve(root, relative);
+    if (target !== root && !target.startsWith(root + NodePath.sep)) {
+      throw new Error(`tar entry escapes the destination: ${name}`);
+    }
+    if (type === "5") {
+      NodeFS.mkdirSync(target, { recursive: true });
+    } else if (type === "0" || type === "\0" || type === "7") {
+      NodeFS.mkdirSync(NodePath.dirname(target), { recursive: true });
+      NodeFS.writeFileSync(target, body, { mode: octal(block, 100, 8) & 0o777 || 0o644 });
+      count += 1;
+    }
+  }
+  return count;
+}
+
+function exists(file) {
+  try {
+    NodeFS.accessSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 与插件的可用性判断共用这份结果；找 SDK 的顺序照 Android Studio 的默认位置。 */
+function probeAndroidSdk(override) {
+  const env = process.env;
+  const home = env.HOME ?? env.USERPROFILE ?? "";
+  const explicit = override || env.ANDROID_HOME?.trim() || env.ANDROID_SDK_ROOT?.trim() || null;
+  const candidates = explicit
+    ? [explicit]
+    : [
+        NodePath.join(home, "Library", "Android", "sdk"),
+        NodePath.join(home, "Android", "Sdk"),
+        NodePath.join(
+          env.LOCALAPPDATA ?? NodePath.join(home, "AppData", "Local"),
+          "Android",
+          "Sdk",
+        ),
+      ];
+  if (!explicit) {
+    for (const directory of (env.PATH ?? env.Path ?? "").split(NodePath.delimiter)) {
+      if (!directory) continue;
+      try {
+        const adb = NodeFS.realpathSync(NodePath.join(directory, exe("adb")));
+        candidates.push(NodePath.dirname(NodePath.dirname(adb)));
+      } catch {
+        // PATH 上这一格没有 adb。
+      }
+    }
+  }
+  const script = (name) => (isWindows ? `${name}.bat` : name);
+  for (const root of candidates) {
+    const adb = exists(NodePath.join(root, "platform-tools", exe("adb")));
+    const emulator = exists(NodePath.join(root, "emulator", exe("emulator")));
+    if (explicit || adb || emulator) {
+      const avdmanager = exists(
+        NodePath.join(root, "cmdline-tools", "latest", "bin", script("avdmanager")),
+      );
+      const legacyAvdmanager =
+        !avdmanager && exists(NodePath.join(root, "tools", "bin", script("avdmanager")));
+      return { root, adb, emulator, avdmanager, legacyAvdmanager };
+    }
+  }
+  return { root: null, adb: false, emulator: false, avdmanager: false, legacyAvdmanager: false };
+}
+
+function hasXcrun() {
+  if (hostPlatform !== "darwin") return false;
+  const result = NodeChildProcess.spawnSync("xcrun", ["--version"], {
+    stdio: "ignore",
+    timeout: 10_000,
+  });
+  return result.status === 0;
+}
+
+/** 把 SDK 的两个目录排到 PATH 最前，并设好 ANDROID_HOME。 */
+function applySdkEnvironment(sdk) {
+  if (!sdk) return;
+  prependPath([NodePath.join(sdk, "platform-tools"), NodePath.join(sdk, "emulator")]);
+  process.env.ANDROID_HOME = sdk;
+}
+
+/** 在本进程里装载一个 Node 入口脚本，就像 `node entry …args` 起的一样。 */
+async function loadEntry(entry, args) {
+  process.argv = [process.argv[0], entry, ...args];
+  await import(NodeURL.pathToFileURL(entry).href);
+}
+
+async function main() {
+  const [mode, ...rest] = process.argv.slice(2);
+  const options = parseArgs(rest);
+  if (mode === "probe") {
+    process.stdout.write(
+      `${JSON.stringify({
+        node: process.version,
+        execPath: process.execPath,
+        electron: process.versions.electron ?? null,
+        platform: hostPlatform,
+        android: probeAndroidSdk(options.sdk),
+        xcrun: hasXcrun(),
+      })}\n`,
+    );
+    return;
+  }
+  if (mode === "node") {
+    const [entry, ...args] = options.rest;
+    if (!entry) throw new Error("helper node: missing entry script");
+    applySdkEnvironment(options.sdk);
+    await loadEntry(entry, args);
+    return;
+  }
+  if (mode === "npm") {
+    const [npmCli, ...args] = options.rest;
+    if (!npmCli || !options.shim) throw new Error("helper npm: missing npm-cli.js or --shim");
+    writeNodeShim(options.shim);
+    prependPath([options.shim]);
+    await loadEntry(npmCli, args);
+    return;
+  }
+  if (mode === "extract") {
+    const [file, destination] = options.rest;
+    if (!file || !destination) throw new Error("helper extract: missing archive or destination");
+    process.stdout.write(`${JSON.stringify({ files: extractTarball(file, destination) })}\n`);
+    return;
+  }
+  if (mode === "run") {
+    const [command, ...args] = options.rest;
+    if (!command) throw new Error("helper run: missing command");
+    applySdkEnvironment(options.sdk);
+    const resolved =
+      command === "emulator" && options.sdk
+        ? NodePath.join(options.sdk, "emulator", exe("emulator"))
+        : command === "adb" && options.sdk
+          ? NodePath.join(options.sdk, "platform-tools", exe("adb"))
+          : command;
+    const child = NodeChildProcess.spawn(resolved, args, { stdio: "inherit", env: process.env });
+    child.on("error", (error) => {
+      process.stderr.write(`${error.message}\n`);
+      process.exitCode = 127;
+    });
+    child.on("exit", (code) => {
+      process.exitCode = code ?? 1;
+    });
+    for (const signal of ["SIGTERM", "SIGINT"]) {
+      process.on(signal, () => child.kill(signal));
+    }
+    return;
+  }
+  throw new Error(`helper: unknown mode ${String(mode)}`);
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+});