zcode-idea 0.0.0-stage → 0.0.1

package/lib/manifest.mjs

@@ -0,0 +1,301 @@
+/**
+ * 插件 zip 的结构校验（下载完成 / 使用 --zip 时、解压之前执行）。
+ *
+ * 职责边界：
+ * - 本模块只校验 zip 自身：sha256/size、条目安全性、主 jar 与 plugin.xml、runtime 完整性；
+ * - 远端 manifest 的验签与字段校验在 remote.mjs；
+ * - manifest 签名通过后，zip 的 sha256/size 来自受信任的 manifest，本模块负责对账。
+ *
+ * 安全策略：拒绝绝对路径、`..`、反斜杠、符号链接、不在 zcode-ide/ 下的条目、重复文件条目。
+ */
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import yauzl from "yauzl";
+import { InstallError } from "./errors.mjs";
+
+export const PACKAGE_PREFIX = "zcode-ide/";
+export const PLUGIN_ID = "dev.zcode.ide";
+
+/* -------------------------------------------------------------------------- */
+/* zip 读取工具                                                                */
+/* -------------------------------------------------------------------------- */
+
+export function openZip(zipPath) {
+  return new Promise((resolve, reject) => {
+    yauzl.open(zipPath, { lazyEntries: true, autoClose: false }, (err, zip) => {
+      if (err) reject(new InstallError(`无法打开插件包 ${zipPath}：${err.message}。文件可能损坏。`));
+      else resolve(zip);
+    });
+  });
+}
+
+export function openZipFromBuffer(buffer, label = "jar") {
+  return new Promise((resolve, reject) => {
+    yauzl.fromBuffer(buffer, { lazyEntries: true, autoClose: false }, (err, zip) => {
+      if (err) reject(new InstallError(`无法读取 ${label}：${err.message}`));
+      else resolve(zip);
+    });
+  });
+}
+
+export function openReadStream(zip, entry) {
+  return new Promise((resolve, reject) => {
+    zip.openReadStream(entry, (err, stream) => {
+      if (err) reject(new InstallError(`读取 zip 条目 ${entry.fileName} 失败：${err.message}`));
+      else resolve(stream);
+    });
+  });
+}
+
+export function readEntryBuffer(zip, entry) {
+  return new Promise((resolve, reject) => {
+    zip.openReadStream(entry, (err, stream) => {
+      if (err) {
+        reject(new InstallError(`读取 zip 条目 ${entry.fileName} 失败：${err.message}`));
+        return;
+      }
+      const chunks = [];
+      stream.on("data", (chunk) => chunks.push(chunk));
+      stream.on("end", () => resolve(Buffer.concat(chunks)));
+      stream.on("error", (streamErr) =>
+        reject(new InstallError(`读取 zip 条目 ${entry.fileName} 失败：${streamErr.message}`)),
+      );
+    });
+  });
+}
+
+/**
+ * 顺序遍历 zip 条目。handler 抛错会终止遍历。
+ * 返回遍历到的条目总数。zip 由调用方负责关闭（遍历结束后仍可 openReadStream）。
+ */
+export function iterateZip(zip, handler) {
+  return new Promise((resolve, reject) => {
+    let count = 0;
+    let settled = false;
+    const finish = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      fn(value);
+    };
+    zip.on("error", (err) =>
+      finish(
+        reject,
+        new InstallError(`插件包内含不安全条目或已损坏（${err.message}）。已中止安装。`),
+      ),
+    );
+    zip.on("end", () => finish(resolve, count));
+    zip.on("entry", (entry) => {
+      const index = count;
+      count += 1;
+      Promise.resolve()
+        .then(() => handler(entry, index))
+        .then(() => {
+          if (!settled) zip.readEntry();
+        })
+        .catch((err) => finish(reject, err));
+    });
+    zip.readEntry();
+  });
+}
+
+/* -------------------------------------------------------------------------- */
+/* 条目安全校验                                                                */
+/* -------------------------------------------------------------------------- */
+
+/** 返回错误原因（中文），安全时返回 null。 */
+export function validateZipEntryName(name) {
+  if (typeof name !== "string" || !name) return "条目名为空";
+  if (name.includes("\0")) return "条目名包含空字符";
+  if (name.includes("\\")) return "条目名包含反斜杠（Windows 路径写法）";
+  if (name.startsWith("/")) return "绝对路径";
+  if (/^[A-Za-z]:/.test(name)) return "带盘符的绝对路径";
+  const segments = name.split("/");
+  if (segments.some((segment) => segment === "..")) return "路径包含 ..（zip-slip）";
+  if (name !== "zcode-ide" && !name.startsWith(PACKAGE_PREFIX)) {
+    return `不在 ${PACKAGE_PREFIX} 目录下`;
+  }
+  return null;
+}
+
+/** zip 条目是否是符号链接（unix mode 高 16 位中的文件类型位）。 */
+export function isSymlinkEntry(entry) {
+  const mode = (entry.externalFileAttributes >>> 16) & 0xffff;
+  return (mode & 0o170000) === 0o120000;
+}
+
+function isDirectoryEntry(entry) {
+  return entry.fileName.endsWith("/");
+}
+
+/* -------------------------------------------------------------------------- */
+/* 校验                                                                        */
+/* -------------------------------------------------------------------------- */
+
+export async function sha256File(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash("sha256");
+    const stream = fs.createReadStream(filePath);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("end", () => resolve(hash.digest("hex")));
+    stream.on("error", (err) => reject(new InstallError(`读取 ${filePath} 失败：${err.message}`)));
+  });
+}
+
+/**
+ * 校验插件 zip。
+ *
+ * @param {string} zipPath
+ * @param {object} [options]
+ * @param {string} [options.expectedSha256] 来自已验签 manifest 的 sha256
+ * @param {number} [options.expectedSize]   来自已验签 manifest 的 size
+ * @param {string} [options.expectedVersion] 来自已验签 manifest 的 pluginVersion
+ * @returns {Promise<object>} zip 摘要信息（供解压进度与汇总使用）
+ */
+export async function validatePluginZip(zipPath, options = {}) {
+  const { expectedSha256, expectedSize, expectedVersion } = options;
+
+  let stat;
+  try {
+    stat = await fsp.stat(zipPath);
+  } catch (err) {
+    throw new InstallError(`插件包不存在或不可读：${zipPath}（${err.message}）`);
+  }
+  if (!stat.isFile()) {
+    throw new InstallError(`插件包不是文件：${zipPath}`);
+  }
+  if (expectedSize !== undefined && expectedSize !== null && stat.size !== Number(expectedSize)) {
+    throw new InstallError(
+      `插件包大小校验失败（期望 ${expectedSize} 字节，实际 ${stat.size} 字节）：${zipPath}。` +
+        "请重新下载，或检查远端产物是否被替换。",
+    );
+  }
+
+  const actualSha256 = await sha256File(zipPath);
+  if (
+    expectedSha256 &&
+    actualSha256.toLowerCase() !== String(expectedSha256).toLowerCase()
+  ) {
+    throw new InstallError(
+      `插件包 sha256 校验失败（期望 ${expectedSha256}，实际 ${actualSha256}）：${zipPath}。` +
+        "请重新下载，或检查远端产物是否被篡改。",
+    );
+  }
+
+  const zip = await openZip(zipPath);
+  let entryCount = 0;
+  let fileCount = 0;
+  let totalBytes = 0;
+  let jarEntry = null;
+  let hasRuntime = false;
+  let hasRuntimeIndex = false;
+  const seenFiles = new Set();
+  let pluginInfo = null;
+
+  try {
+    await iterateZip(zip, async (entry) => {
+      entryCount += 1;
+      const nameError = validateZipEntryName(entry.fileName);
+      if (nameError) {
+        throw new InstallError(
+          `插件包内含不安全条目「${entry.fileName}」：${nameError}。已中止安装。`,
+        );
+      }
+      if (isSymlinkEntry(entry)) {
+        throw new InstallError(`插件包内含符号链接条目「${entry.fileName}」，出于安全考虑拒绝安装。`);
+      }
+      if (!isDirectoryEntry(entry)) {
+        if (seenFiles.has(entry.fileName)) {
+          throw new InstallError(`插件包内含重复文件条目「${entry.fileName}」，拒绝解压。`);
+        }
+        seenFiles.add(entry.fileName);
+        fileCount += 1;
+        totalBytes += entry.uncompressedSize;
+      }
+      if (/^zcode-ide\/lib\/zcode-ide-[^/]+\.jar$/i.test(entry.fileName) && !jarEntry) {
+        jarEntry = entry;
+      }
+      if (entry.fileName.startsWith("zcode-ide/runtime/")) hasRuntime = true;
+      if (entry.fileName === "zcode-ide/runtime/web/index.html") hasRuntimeIndex = true;
+    });
+
+    if (!jarEntry) {
+      throw new InstallError(
+        "插件包不完整：未找到 zcode-ide/lib/zcode-ide-*.jar。请重新构建插件后发布。",
+      );
+    }
+    if (hasRuntime && !hasRuntimeIndex) {
+      throw new InstallError(
+        "插件包含 runtime/ 但缺少 runtime/web/index.html，完整包可能被截断。请重新构建 runtime。",
+      );
+    }
+
+    const jarBuffer = await readEntryBuffer(zip, jarEntry);
+    pluginInfo = await inspectPluginJar(jarBuffer, jarEntry.fileName);
+    if (!pluginInfo.version) {
+      throw new InstallError(
+        `主 jar（${jarEntry.fileName}）的 META-INF/plugin.xml 缺少 <version>，无法判断插件版本。`,
+      );
+    }
+    if (expectedVersion && pluginInfo.version !== expectedVersion) {
+      throw new InstallError(
+        `插件版本不一致：manifest=${expectedVersion}，主 jar=${pluginInfo.version}。` +
+          "请检查远端 manifest 与 zip 是否配套。",
+      );
+    }
+  } finally {
+    try {
+      zip.close();
+    } catch {
+      /* 已关闭 */
+    }
+  }
+
+  return {
+    zipPath,
+    sha256: actualSha256,
+    size: stat.size,
+    pluginVersion: pluginInfo.version,
+    pluginId: pluginInfo.id,
+    entryCount,
+    fileCount,
+    totalBytes,
+    jarName: jarEntry.fileName,
+    hasRuntime,
+  };
+}
+
+/** 读取主 jar 内的 META-INF/plugin.xml，确认插件 id 与版本。 */
+export async function inspectPluginJar(jarBuffer, jarLabel = "主 jar") {
+  const zip = await openZipFromBuffer(jarBuffer, jarLabel);
+  let pluginXml = null;
+  try {
+    await iterateZip(zip, async (entry) => {
+      if (entry.fileName === "META-INF/plugin.xml") {
+        pluginXml = await readEntryBuffer(zip, entry);
+      }
+    });
+  } finally {
+    try {
+      zip.close();
+    } catch {
+      /* 已关闭 */
+    }
+  }
+
+  if (!pluginXml) {
+    throw new InstallError(`${jarLabel} 内缺少 META-INF/plugin.xml，不是有效的 JetBrains 插件。`);
+  }
+
+  const text = pluginXml.toString("utf8");
+  const idMatch = /<id>\s*([^<\s]+)\s*<\/id>/.exec(text);
+  if (!idMatch || idMatch[1] !== PLUGIN_ID) {
+    throw new InstallError(
+      `主 jar 的插件 id 不是 ${PLUGIN_ID}（实际：${idMatch ? idMatch[1] : "未找到 <id>"}）。` +
+        "这可能不是 ZCode IDE 插件包。",
+    );
+  }
+  const versionMatch = /<version>\s*([^<\s]+)\s*<\/version>/.exec(text);
+  return { id: idMatch[1], version: versionMatch ? versionMatch[1] : "" };
+}

package/lib/plugin-signing-public.pem

@@ -0,0 +1,3 @@
+-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEA1hbJOUxCdNJ0M45cwNHmOVg5DQ6USQVjhs6lE/YvNNo=
+-----END PUBLIC KEY-----

package/lib/processes.mjs

@@ -0,0 +1,194 @@
+/**
+ * 关闭 IDE 进程。
+ *
+ * 只处理所选目标对应的产品进程（同一产品多版本只关一次），
+ * 先优雅关闭（Windows: taskkill 不带 /F；macOS/Linux: SIGTERM），
+ * 轮询到超时仍存活才强制结束（Windows /F；Unix SIGKILL）。
+ */
+
+import { spawnSync } from "node:child_process";
+import { setTimeout as sleep } from "node:timers/promises";
+import path from "node:path";
+import { InstallError } from "./errors.mjs";
+import { info, warn } from "./log.mjs";
+import { getProcessNames, PRODUCT_BY_ID } from "./products.mjs";
+
+const POLL_INTERVAL_MS = 500;
+
+/** 列出当前运行的进程（只匹配传入的进程名）。 */
+export function listProcesses(names, platform = process.platform) {
+  if (!names.length) return [];
+  return platform === "win32" ? listWindowsProcesses(names) : listUnixProcesses(names);
+}
+
+function listWindowsProcesses(names) {
+  const found = new Map();
+  for (const name of names) {
+    const result = spawnSync(
+      "tasklist",
+      ["/FI", `IMAGENAME eq ${name}`, "/FO", "CSV", "/NH"],
+      { encoding: "utf8", windowsHide: true },
+    );
+    if (result.error) {
+      throw new InstallError(
+        `无法执行 tasklist（${result.error.message}）。请在 Windows 上运行，或手动关闭 IDE。`,
+      );
+    }
+    for (const line of String(result.stdout || "").split(/\r?\n/)) {
+      const match = /^"([^"]+)","(\d+)"/.exec(line.trim());
+      if (!match) continue;
+      found.set(`${match[1].toLowerCase()}:${match[2]}`, {
+        name: match[1],
+        pid: Number(match[2]),
+      });
+    }
+  }
+  return [...found.values()];
+}
+
+function listUnixProcesses(names) {
+  const result = spawnSync("ps", ["-A", "-o", "pid=,comm="], { encoding: "utf8" });
+  if (result.error) {
+    throw new InstallError(
+      `无法执行 ps（${result.error.message}）。请手动关闭 IDE 后重试。`,
+    );
+  }
+  const wanted = new Set(names.map((name) => name.toLowerCase()));
+  const found = [];
+  for (const line of String(result.stdout || "").split(/\r?\n/)) {
+    const match = /^\s*(\d+)\s+(.+?)\s*$/.exec(line);
+    if (!match) continue;
+    const base = path.basename(match[2]).toLowerCase();
+    if (!wanted.has(base)) continue;
+    found.push({ name: base, pid: Number(match[1]) });
+  }
+  return found;
+}
+
+/**
+ * 关闭所选目标对应的 IDE。
+ *
+ * @param {object} params
+ * @param {Array} params.targets 已选择的目标
+ * @param {"win32"|"darwin"|"linux"|string} [params.platform]
+ * @param {number} [params.timeoutSec]
+ * @param {boolean} [params.dryRun]
+ * @param {boolean} [params.assumeYes] 传了 --yes
+ * @param {boolean} [params.interactive] 是否交互终端
+ * @param {(message: string) => Promise<boolean>} [params.confirm]
+ */
+export async function closeSelectedProcesses({
+  targets,
+  platform = process.platform,
+  timeoutSec = 30,
+  dryRun = false,
+  assumeYes = false,
+  interactive = false,
+  confirm = null,
+}) {
+  const products = [];
+  for (const target of targets) {
+    const product = target.productId ? PRODUCT_BY_ID.get(target.productId) : null;
+    if (product && !products.some((item) => item.id === product.id)) products.push(product);
+  }
+
+  if (!products.length) {
+    info("未能从目标识别出 IDE 产品，跳过关闭 IDE。");
+    return { running: [], skipped: true };
+  }
+
+  const names = [...new Set(products.flatMap((product) => getProcessNames(product, platform)))];
+  const running = listProcesses(names, platform);
+  const productLabel = products.map((product) => product.name).join("、");
+
+  if (!running.length) {
+    info(`没有检测到运行中的 ${productLabel} 进程，继续安装。`);
+    return { running: [] };
+  }
+
+  info(`检测到以下 ${productLabel} 进程：`);
+  for (const proc of running) info(`  - ${proc.name}（pid ${proc.pid}）`);
+
+  if (dryRun) {
+    info("dry-run：跳过关闭 IDE（真实执行时会先优雅关闭，超时后再强制结束）。");
+    return { running, dryRun: true };
+  }
+
+  if (!assumeYes) {
+    if (!interactive || typeof confirm !== "function") {
+      warn("非交互环境未传 --yes，跳过关闭 IDE。若安装失败，请先手动退出 IDE 后重试。");
+      return { running, skipped: true };
+    }
+    const confirmed = await confirm(
+      `将关闭以上 ${running.length} 个进程（未保存内容可能丢失，IDE 默认失焦时保存），是否继续？`,
+    );
+    if (!confirmed) {
+      throw new InstallError("已取消：请先手动关闭 IDE，再重新运行安装命令。");
+    }
+  }
+
+  const attemptedNames = [...new Set(running.map((proc) => proc.name))];
+  for (const name of attemptedNames) sendTerminate(name, platform);
+  info(`已请求关闭 ${attemptedNames.join("、")}，等待退出（最多 ${timeoutSec} 秒）…`);
+
+  const isStillRunning = () => {
+    const attempted = new Set(attemptedNames.map((name) => name.toLowerCase()));
+    return listProcesses(names, platform).filter((proc) => attempted.has(proc.name.toLowerCase()));
+  };
+
+  const deadline = Date.now() + timeoutSec * 1000;
+  let left = isStillRunning();
+  while (left.length > 0 && Date.now() < deadline) {
+    await sleep(POLL_INTERVAL_MS);
+    left = isStillRunning();
+  }
+
+  if (left.length === 0) {
+    info("IDE 已退出。");
+    return { running };
+  }
+
+  const forcedNames = [...new Set(left.map((proc) => proc.name))];
+  warn(
+    `等待 ${timeoutSec} 秒后仍有 ${left.length} 个进程未退出，强制结束：${forcedNames.join("、")}`,
+  );
+  for (const name of forcedNames) {
+    const pids = left.filter((proc) => proc.name === name).map((proc) => proc.pid);
+    sendForceKill(name, platform, pids);
+  }
+  await sleep(1000);
+
+  left = isStillRunning();
+  if (left.length > 0) {
+    throw new InstallError(
+      `无法关闭 IDE 进程：${[...new Set(left.map((proc) => proc.name))].join("、")}。` +
+        "请手动退出后重试（可用 --timeout 增加等待时间）。",
+    );
+  }
+  info("已强制结束 IDE 进程。");
+  return { running };
+}
+
+function sendTerminate(name, platform) {
+  if (platform === "win32") {
+    spawnSync("taskkill", ["/IM", name], { encoding: "utf8", windowsHide: true });
+    return;
+  }
+  const result = spawnSync("pkill", ["-TERM", "-x", name], { encoding: "utf8" });
+  if (result.error) warn(`pkill 不可用（${result.error.message}），请手动关闭 ${name}。`);
+}
+
+function sendForceKill(name, platform, pids = []) {
+  if (platform === "win32") {
+    spawnSync("taskkill", ["/F", "/IM", name], { encoding: "utf8", windowsHide: true });
+    return;
+  }
+  if (platform === "darwin" && pids.length > 0) {
+    const result = spawnSync("kill", ["-9", ...pids.map((pid) => String(pid))], {
+      encoding: "utf8",
+    });
+    if (!result.error && result.status === 0) return;
+  }
+  const result = spawnSync("pkill", ["-9", "-x", name], { encoding: "utf8" });
+  if (result.error) warn(`pkill 不可用（${result.error.message}），请手动关闭 ${name}。`);
+}