zcode-idea 0.0.0-stage → 0.0.1

package/lib/download.mjs

@@ -0,0 +1,294 @@
+/**
+ * 插件包下载与本地缓存。
+ *
+ * 缓存位置：`${ZCODE_DATA_BASE_DIR:-~/.zcode}/ide/plugin-cache/<sha256>.zip`
+ * - 命中且 sha256/size 一致 → 直接复用；
+ * - 未命中 → 下载到 `<sha256>.zip.part`，校验后原子改名为正式缓存；
+ * - 下载失败重试 3 次（退避 0.5s/1s），最终失败给出可操作提示（可用 --zip 离线）。
+ */
+
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { setTimeout as sleep } from "node:timers/promises";
+import { InstallError } from "./errors.mjs";
+import { formatBytes, info, warn } from "./log.mjs";
+import { sha256File } from "./manifest.mjs";
+
+const DOWNLOAD_TIMEOUT_MS = 60 * 60_000;
+const RETRY_BACKOFF_MS = 500;
+// 只有 sha256 命名的文件才是缓存产物；其它 *.zip 可能是用户手工放入的文件，不能碰。
+const CACHE_FILE_PATTERN = /^([0-9a-f]{64})\.zip(\.part)?$/i;
+
+/** 插件缓存目录。 */
+export function getPluginCacheDir(env = process.env) {
+  const override = env.ZCODE_DATA_BASE_DIR?.trim();
+  const root = override ? path.resolve(override) : path.join(os.homedir(), ".zcode");
+  return path.join(root, "ide", "plugin-cache");
+}
+
+export function getCachedArchivePath(sha256, env = process.env) {
+  return path.join(getPluginCacheDir(env), `${sha256}.zip`);
+}
+
+/** 仅按大小判断缓存是否可能存在（dry-run 提示用，不做 sha 校验）。 */
+export function isCachePresent(sha256, size, env = process.env) {
+  try {
+    const stat = fs.statSync(getCachedArchivePath(sha256, env));
+    return stat.isFile() && stat.size === size;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 清理插件包缓存。
+ *
+ * 只处理缓存目录下以 sha256 命名的 `<64位十六进制>.zip` 与下载残留
+ * `<64位十六进制>.zip.part`：
+ * - `keep` 中的 sha256（大小写不敏感）对应的 zip 保留；
+ * - 其余缓存 zip 与全部缓存 `.part` 删除（`keep` 为空表示全部清理）；
+ * - 其它文件与子目录（包括非 sha256 命名的 `*.zip`）一律不动；
+ * - 单个文件删除失败只记入 `failed`，不中断整体清理。
+ *
+ * 目录不存在时返回空结果，不抛错；本函数不打印日志，由调用方决定输出。
+ *
+ * @param {object} [params]
+ * @param {NodeJS.ProcessEnv} [params.env]
+ * @param {string[]} [params.keep] 需要保留的 sha256 列表
+ * @param {boolean} [params.dryRun] 只扫描不删除（CLI dry-run 提示用）
+ * @returns {Promise<{
+ *   removed: Array<{path: string, size: number}>,
+ *   freedBytes: number,
+ *   keptCount: number,
+ *   failed: Array<{path: string, error: string}>,
+ * }>}
+ */
+export async function prunePluginCache({ env = process.env, keep = [], dryRun = false } = {}) {
+  const keepSet = new Set(
+    (Array.isArray(keep) ? keep : [])
+      .map((value) => String(value ?? "").trim().toLowerCase())
+      .filter(Boolean),
+  );
+  const cacheDir = getPluginCacheDir(env);
+
+  let entries;
+  try {
+    entries = await fsp.readdir(cacheDir, { withFileTypes: true });
+  } catch (err) {
+    if (err?.code === "ENOENT") {
+      return { removed: [], freedBytes: 0, keptCount: 0, failed: [] };
+    }
+    throw new InstallError(`无法读取插件缓存目录 ${cacheDir}：${err.message}`);
+  }
+
+  const result = { removed: [], freedBytes: 0, keptCount: 0, failed: [] };
+  const candidates = entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name)
+    .map((name) => ({ name, match: CACHE_FILE_PATTERN.exec(name) }))
+    .filter((item) => item.match)
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  for (const { name, match } of candidates) {
+    const sha256 = match[1].toLowerCase();
+    const isPart = Boolean(match[2]);
+    // 只有正式 zip 能按 sha256 保留；.part 是下载残留，一律清掉。
+    if (!isPart && keepSet.has(sha256)) {
+      result.keptCount += 1;
+      continue;
+    }
+
+    const filePath = path.join(cacheDir, name);
+    let size = 0;
+    try {
+      size = (await fsp.stat(filePath)).size;
+    } catch {
+      // 读不到大小不影响删除，removed 里按 0 记录。
+    }
+
+    if (dryRun) {
+      result.removed.push({ path: filePath, size });
+      result.freedBytes += size;
+      continue;
+    }
+
+    try {
+      await fsp.rm(filePath, { force: true });
+      result.removed.push({ path: filePath, size });
+      result.freedBytes += size;
+    } catch (err) {
+      result.failed.push({ path: filePath, error: err?.message ?? String(err) });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * 确保插件包存在且通过 sha256/size 校验。
+ *
+ * @param {object} params
+ * @param {string} params.archiveUrl
+ * @param {string} params.sha256
+ * @param {number} params.size
+ * @param {number} [params.retries]
+ * @param {NodeJS.ProcessEnv} [params.env]
+ * @returns {Promise<{zipPath: string, fromCache: boolean}>}
+ */
+export async function ensurePluginArchive({
+  archiveUrl,
+  sha256,
+  size,
+  retries = 3,
+  env = process.env,
+}) {
+  if (!archiveUrl) throw new InstallError("缺少插件包下载地址");
+  if (!/^[0-9a-f]{64}$/i.test(String(sha256 ?? ""))) {
+    throw new InstallError("插件包 sha256 不合法，拒绝下载");
+  }
+  if (!Number.isInteger(size) || size <= 0) {
+    throw new InstallError(`插件包大小不合法：${size}`);
+  }
+
+  const cacheDir = getPluginCacheDir(env);
+  try {
+    await fsp.mkdir(cacheDir, { recursive: true });
+  } catch (err) {
+    throw new InstallError(`无法创建插件缓存目录 ${cacheDir}：${err.message}`);
+  }
+
+  const finalPath = path.join(cacheDir, `${sha256}.zip`);
+  const partPath = `${finalPath}.part`;
+
+  if (isCachePresent(sha256, size, env)) {
+    const cachedSha256 = await sha256File(finalPath).catch(() => null);
+    if (cachedSha256 === sha256.toLowerCase()) {
+      info(`使用本地缓存插件包：${finalPath}`);
+      return { zipPath: finalPath, fromCache: true };
+    }
+    warn(`本地缓存 sha256 不一致，删除后重新下载：${finalPath}`);
+    await fsp.rm(finalPath, { force: true }).catch(() => {});
+  } else if (fs.existsSync(finalPath)) {
+    warn(`本地缓存大小不一致，删除后重新下载：${finalPath}`);
+    await fsp.rm(finalPath, { force: true }).catch(() => {});
+  }
+
+  let lastError = null;
+  for (let attempt = 1; attempt <= retries; attempt += 1) {
+    try {
+      const received = await downloadToFile(archiveUrl, partPath, size);
+      if (received !== size) {
+        throw new Error(`下载大小不一致：期望 ${size} 字节，实际 ${received} 字节`);
+      }
+      const actualSha256 = await sha256File(partPath);
+      if (actualSha256 !== sha256.toLowerCase()) {
+        throw new Error(`下载后 sha256 校验失败：期望 ${sha256}，实际 ${actualSha256}`);
+      }
+      await fsp.rename(partPath, finalPath);
+      info(`插件包下载并校验完成：${finalPath}`);
+      return { zipPath: finalPath, fromCache: false };
+    } catch (err) {
+      lastError = err;
+      await fsp.rm(partPath, { force: true }).catch(() => {});
+      if (attempt < retries) {
+        const delay = RETRY_BACKOFF_MS * attempt;
+        warn(
+          `下载失败（第 ${attempt}/${retries} 次）：${err?.message ?? "未知错误"}；` +
+            `${delay}ms 后重试…`,
+        );
+        await sleep(delay);
+      }
+    }
+  }
+
+  throw new InstallError(
+    `下载插件包失败（已重试 ${retries} 次）：${lastError?.message ?? "未知错误"}。` +
+      "请检查网络或稍后重试；离线环境可用 --zip <本地 zip> 安装。",
+  );
+}
+
+async function downloadToFile(archiveUrl, destination, expectedSize) {
+  const response = await fetch(archiveUrl, {
+    headers: {
+      "User-Agent": "zcode-idea-installer",
+      Accept: "application/zip, application/octet-stream",
+    },
+    signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+  });
+  if (!response.ok) {
+    if (response.status === 404) {
+      throw new Error(`插件包不存在（HTTP 404）：${archiveUrl}`);
+    }
+    throw new Error(`下载失败：HTTP ${response.status} ${response.statusText}`);
+  }
+  if (!response.body) throw new Error("下载响应没有响应体");
+
+  const headerSize = Number(response.headers.get("content-length")) || 0;
+  const total = expectedSize > 0 ? expectedSize : headerSize;
+  const progress = createDownloadProgress(total);
+  const startedAt = Date.now();
+  let received = 0;
+
+  const meter = new Transform({
+    transform(chunk, _encoding, callback) {
+      received += chunk.length;
+      progress.update(received, startedAt);
+      callback(null, chunk);
+    },
+  });
+
+  try {
+    await pipeline(
+      Readable.fromWeb(response.body),
+      meter,
+      fs.createWriteStream(destination),
+    );
+  } finally {
+    progress.finish();
+  }
+  return received;
+}
+
+function createDownloadProgress(totalBytes) {
+  const tty = Boolean(process.stdout.isTTY);
+  let lastBucket = -1;
+  let lastPrintAt = 0;
+  let printedTty = false;
+
+  return {
+    update(received, startedAt) {
+      const percent = totalBytes > 0 ? Math.min(100, Math.floor((received / totalBytes) * 100)) : 0;
+      const elapsedSeconds = Math.max(0.001, (Date.now() - startedAt) / 1000);
+      const speed = received / elapsedSeconds;
+
+      if (tty) {
+        const now = Date.now();
+        if (percent < 100 && now - lastPrintAt < 100) return;
+        lastPrintAt = now;
+        printedTty = true;
+        process.stdout.write(
+          `\r[zcode-idea] 下载中 ${String(percent).padStart(3, " ")}%｜` +
+            `${formatBytes(received)}/${formatBytes(totalBytes)}｜` +
+            `${formatBytes(speed)}/s    `,
+        );
+        return;
+      }
+
+      const bucket = Math.floor(percent / 10);
+      if (bucket > lastBucket) {
+        lastBucket = bucket;
+        info(
+          `下载进度 ${percent}%（${formatBytes(received)}/${formatBytes(totalBytes)}，` +
+            `${formatBytes(speed)}/s）`,
+        );
+      }
+    },
+    finish() {
+      if (tty && printedTty) process.stdout.write("\n");
+    },
+  };
+}

package/lib/errors.mjs

@@ -0,0 +1,17 @@
+/** 用法错误（参数不合法等），CLI 以退出码 2 结束。 */
+export class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+    this.exitCode = 2;
+  }
+}
+
+/** 安装/校验失败，CLI 以退出码 1 结束。 */
+export class InstallError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "InstallError";
+    this.exitCode = 1;
+  }
+}

package/lib/installed.mjs

@@ -0,0 +1,86 @@
+/**
+ * 读取目标 plugins 目录中已安装的 ZCode 插件版本。
+ *
+ * 版本来源：`<pluginsDir>/zcode-ide/lib/zcode-ide-*.jar` 内的 META-INF/plugin.xml。
+ * 读取失败不抛错（避免因为一个损坏的旧安装阻断整个流程），由调用方按未安装处理并提示。
+ */
+
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { iterateZip, openZip, readEntryBuffer } from "./manifest.mjs";
+
+/**
+ * @param {string} pluginsDir
+ * @returns {Promise<{installed: boolean, version: string|null, jarPath: string|null, error: string|null}>}
+ */
+export async function readInstalledPlugin(pluginsDir) {
+  const pluginDir = path.join(pluginsDir, "zcode-ide");
+  if (!fs.existsSync(pluginDir)) {
+    return { installed: false, version: null, jarPath: null, error: null };
+  }
+
+  const libDir = path.join(pluginDir, "lib");
+  let entries;
+  try {
+    entries = await fsp.readdir(libDir);
+  } catch (err) {
+    return {
+      installed: true,
+      version: null,
+      jarPath: null,
+      error: `无法读取 lib 目录：${err.message}`,
+    };
+  }
+
+  const jarName = entries.find((name) => /^zcode-ide-.*\.jar$/i.test(name));
+  if (!jarName) {
+    return {
+      installed: true,
+      version: null,
+      jarPath: null,
+      error: "lib 下没有 zcode-ide-*.jar",
+    };
+  }
+
+  const jarPath = path.join(libDir, jarName);
+  let zip;
+  try {
+    zip = await openZip(jarPath);
+  } catch (err) {
+    return { installed: true, version: null, jarPath, error: err.message };
+  }
+
+  try {
+    let pluginXml = null;
+    await iterateZip(zip, async (entry) => {
+      if (entry.fileName === "META-INF/plugin.xml") {
+        pluginXml = await readEntryBuffer(zip, entry);
+      }
+    });
+    if (!pluginXml) {
+      return {
+        installed: true,
+        version: null,
+        jarPath,
+        error: "jar 内缺少 META-INF/plugin.xml",
+      };
+    }
+    const text = pluginXml.toString("utf8");
+    const version = /<version>\s*([^<\s]+)\s*<\/version>/.exec(text)?.[1] ?? null;
+    return {
+      installed: true,
+      version,
+      jarPath,
+      error: version ? null : "plugin.xml 缺少 <version>",
+    };
+  } catch (err) {
+    return { installed: true, version: null, jarPath, error: err.message };
+  } finally {
+    try {
+      zip.close();
+    } catch {
+      /* 已关闭 */
+    }
+  }
+}

package/lib/launch.mjs

@@ -0,0 +1,214 @@
+/**
+ * 查找并启动 IDE 可执行文件。
+ *
+ * 搜索顺序按平台覆盖：JetBrains 安装目录、LOCALAPPDATA\Programs、Toolbox、
+ * /Applications（macOS）、/opt 与 /snap（Linux）；优先选择路径中包含目标版本的候选。
+ * 找不到只提示“请手动打开”，不算安装失败。
+ */
+
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { info, warn } from "./log.mjs";
+import { inferProductFromName, PRODUCT_BY_ID, PRODUCTS } from "./products.mjs";
+
+/**
+ * @returns {string | null} 可执行文件的绝对路径
+ */
+export function findLaunchCommand(target, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const home = options.home ?? os.homedir();
+
+  const product =
+    (target.productId ? PRODUCT_BY_ID.get(target.productId) : null) ??
+    PRODUCTS.find((item) => item.name === target.productName) ??
+    null;
+  if (!product) return null;
+
+  let candidates = [];
+  if (platform === "win32") candidates = windowsCandidates(product, target, env, home);
+  else if (platform === "darwin") candidates = macCandidates(product, target, env, home);
+  else candidates = linuxCandidates(product, target, env, home);
+
+  const existing = [...new Set(candidates)].filter((candidate) => isFile(candidate));
+  if (!existing.length) return null;
+
+  const version = target.version || "";
+  existing.sort((a, b) => scoreCandidate(b, version) - scoreCandidate(a, version));
+  return existing[0];
+}
+
+function windowsCandidates(product, target, env, home) {
+  const programFiles = env.PROGRAMFILES || "C:\\Program Files";
+  const localAppData = env.LOCALAPPDATA || path.join(home, "AppData", "Local");
+  const homes = [];
+
+  for (const dir of listDirs(path.join(programFiles, "JetBrains"))) {
+    if (matchesProductName(dir.name, product)) homes.push(dir.path);
+  }
+  for (const dir of listDirs(path.join(localAppData, "Programs"))) {
+    if (matchesProductName(dir.name, product)) homes.push(dir.path);
+  }
+  for (const versionDir of toolboxVersionHomes(
+    path.join(localAppData, "JetBrains", "Toolbox", "apps"),
+    product,
+  )) {
+    homes.push(versionDir);
+  }
+  if (product.id === "androidStudio") {
+    homes.push(path.join(programFiles, "Android", "Android Studio"));
+  }
+
+  // --target 指向 IDE 安装目录下的 plugins 时，父目录就是 IDE home
+  homes.push(path.dirname(target.pluginsDir));
+
+  return homes.flatMap((homeDir) => product.winExes.map((exe) => path.join(homeDir, "bin", exe)));
+}
+
+function macCandidates(product, target, env, home) {
+  const candidates = [];
+  for (const root of ["/Applications", path.join(home, "Applications")]) {
+    for (const app of product.macApps) {
+      for (const bin of product.macBins) {
+        candidates.push(path.join(root, app, "Contents", "MacOS", bin));
+      }
+    }
+  }
+
+  // --target 指向 *.app/Contents/plugins 时直接定位该 app
+  const segments = target.pluginsDir.split(/[\\/]+/).filter(Boolean);
+  const appIndex = segments.findIndex((segment) => /\.app$/i.test(segment));
+  if (appIndex >= 0) {
+    const prefix = segments.slice(0, appIndex + 1).join(path.sep);
+    const appRoot = prefix.startsWith(path.sep) ? prefix : `${path.sep}${prefix}`;
+    for (const bin of product.macBins) {
+      candidates.push(path.join(appRoot, "Contents", "MacOS", bin));
+    }
+  }
+
+  const appSupport = path.join(home, "Library", "Application Support");
+  for (const versionDir of toolboxVersionHomes(
+    path.join(appSupport, "JetBrains", "Toolbox", "apps"),
+    product,
+  )) {
+    for (const app of product.macApps) {
+      for (const bin of product.macBins) {
+        candidates.push(path.join(versionDir, app, "Contents", "MacOS", bin));
+      }
+    }
+    for (const bin of product.macBins) {
+      candidates.push(path.join(versionDir, "Contents", "MacOS", bin));
+    }
+  }
+  return candidates;
+}
+
+function linuxCandidates(product, target, env, home) {
+  const homes = [];
+  for (const dir of listDirs("/opt")) {
+    if (matchesProductName(dir.name, product)) homes.push(dir.path);
+  }
+  homes.push(path.dirname(target.pluginsDir));
+
+  for (const versionDir of toolboxVersionHomes(
+    path.join(home, ".local", "share", "JetBrains", "Toolbox", "apps"),
+    product,
+  )) {
+    homes.push(versionDir);
+  }
+  for (const snapDir of listDirs("/snap")) {
+    if (!matchesProductName(snapDir.name, product)) continue;
+    homes.push(path.join(snapDir.path, "current"));
+  }
+
+  return homes.flatMap((homeDir) =>
+    product.linuxScripts.map((script) => path.join(homeDir, "bin", script)),
+  );
+}
+
+function toolboxVersionHomes(appsRoot, product) {
+  const result = [];
+  for (const productDir of listDirs(appsRoot)) {
+    const keyMatched = product.toolboxKeys.some(
+      (key) => key.toLowerCase() === productDir.name.toLowerCase(),
+    );
+    if (!keyMatched && !matchesProductName(productDir.name, product)) continue;
+    for (const channelDir of listDirs(productDir.path)) {
+      for (const versionDir of listDirs(channelDir.path)) result.push(versionDir.path);
+    }
+  }
+  return result;
+}
+
+function matchesProductName(name, product) {
+  const inferred = inferProductFromName(name);
+  if (inferred?.product.id === product.id) return true;
+  const lower = name.toLowerCase();
+  if (product.toolboxKeys.some((key) => key.toLowerCase() === lower)) return true;
+  return product.macApps.some((app) => app.replace(/\.app$/i, "").toLowerCase() === lower);
+}
+
+function scoreCandidate(candidate, version) {
+  if (!version) return 0;
+  return candidate.toLowerCase().includes(version.toLowerCase()) ? 1 : 0;
+}
+
+function listDirs(dir) {
+  try {
+    return fs
+      .readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
+      .map((entry) => ({ name: entry.name, path: path.join(dir, entry.name) }))
+      .filter((entry) => isDirectory(entry.path));
+  } catch {
+    return [];
+  }
+}
+
+function isDirectory(target) {
+  try {
+    return fs.statSync(target).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isFile(target) {
+  try {
+    return fs.statSync(target).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 以 detached 方式启动 IDE，不阻塞安装器。
+ * @returns {Promise<boolean>} 是否成功拉起
+ */
+export function launchDetached(exe) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (ok) => {
+      if (settled) return;
+      settled = true;
+      resolve(ok);
+    };
+    try {
+      const child = spawn(exe, [], { detached: true, stdio: "ignore", windowsHide: false });
+      child.once("error", (err) => {
+        warn(`启动失败：${exe} — ${err.message}。请手动打开 IDE。`);
+        finish(false);
+      });
+      child.once("spawn", () => {
+        child.unref();
+        info(`已启动：${exe}`);
+        finish(true);
+      });
+    } catch (err) {
+      warn(`启动失败：${exe} — ${err.message}。请手动打开 IDE。`);
+      finish(false);
+    }
+  });
+}

package/lib/log.mjs

@@ -0,0 +1,36 @@
+/**
+ * 控制台输出统一走这里，保证每行都带 [zcode-idea] 前缀。
+ * 进度条在 TTY 下用 \r 原地刷新，非 TTY（CI/管道）降级为每 10% 一行。
+ */
+
+const PREFIX = "[zcode-idea]";
+
+export function info(message) {
+  console.log(`${PREFIX} ${message}`);
+}
+
+export function warn(message) {
+  console.warn(`${PREFIX} 警告：${message}`);
+}
+
+export function error(message) {
+  console.error(`${PREFIX} 错误：${message}`);
+}
+
+/** 交互能力判定：stdin 与 stdout 都是 TTY 才算交互环境。 */
+export function isInteractive() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+export function formatBytes(bytes) {
+  const n = Number(bytes) || 0;
+  if (n < 1024) return `${n} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let value = n / 1024;
+  let index = 0;
+  while (value >= 1024 && index < units.length - 1) {
+    value /= 1024;
+    index += 1;
+  }
+  return `${value.toFixed(value >= 100 ? 0 : 1)} ${units[index]}`;
+}