dsh-windows-mcp 0.1.0 → 0.2.0

package/lib/mirrors.js

@@ -0,0 +1,236 @@
+/**
+ * dsh-windows-mcp — PyPI mirror discovery (host side).
+ *
+ * Downloading `windows-mcp` from PyPI directly is unreliable on some networks
+ * (measured on this project's own machine: the PyPI JSON API took 22 s and the
+ * index page timed out, while mainland mirrors answered in ~100–500 ms). The
+ * install and the version check therefore both run through this module:
+ *
+ *   1. **Probe.** For every mirror in `MIRROR_CANDIDATES`, fetch just
+ *      `<index>/windows-mcp/` (≈10 KB — never the 47 MB root page) and download a
+ *      ranged sample of a real wheel, timing both.
+ *   2. **Rank.** Successful mirrors are ordered by measured throughput, index
+ *      latency breaking ties. A hidden official fallback stays in the order
+ *      list so a mirror that is fast now but fails mid-install still has a next
+ *      address to try.
+ *
+ * Measured on this project's machine (2026-10, 256 KB sample): USTC ≈1.7 MB/s,
+ * Tencent ≈1.4 MB/s, Aliyun ≈1.0 MB/s, Huawei ≈0.8 MB/s, NJU ≈0.6 MB/s; PyPI
+ * itself timed out and TUNA answered 403 (IP-blocked for this network).
+ *
+ * Network access is injected (`options.fetchImpl`), so the whole module is
+ * unit-testable without a socket, and every failure is reported as a value
+ * instead of an exception.
+ */
+import { entryForVersion, latestStableEntry, latestStableVersion, parseIndex, projectIndexUrl } from "./pypi.js";
+
+/** Mirrors this plugin knows about. `official` is always kept as last resort. */
+export const MIRROR_CANDIDATES = Object.freeze([
+  Object.freeze({ id: "pypi", label: "PyPI", indexUrl: "https://pypi.org/simple", official: true }),
+  Object.freeze({ id: "ustc", label: "USTC 中科大", indexUrl: "https://mirrors.ustc.edu.cn/pypi/simple", official: false }),
+  Object.freeze({ id: "aliyun", label: "阿里云", indexUrl: "https://mirrors.aliyun.com/pypi/simple", official: false }),
+  Object.freeze({ id: "tencent", label: "腾讯云", indexUrl: "https://mirrors.cloud.tencent.com/pypi/simple", official: false }),
+  Object.freeze({ id: "huawei", label: "华为云", indexUrl: "https://repo.huaweicloud.com/repository/pypi/simple", official: false }),
+  Object.freeze({ id: "nju", label: "南京大学", indexUrl: "https://mirrors.nju.edu.cn/pypi/web/simple", official: false }),
+  Object.freeze({ id: "tuna", label: "清华 TUNA", indexUrl: "https://pypi.tuna.tsinghua.edu.cn/simple", official: false }),
+]);
+
+/** Probe knobs: a small ranged read is enough to tell a fast mirror from a slow one. */
+export const PROBE_DEFAULTS = Object.freeze({
+  project: "windows-mcp",
+  version: null,
+  timeoutMs: 8000,
+  sampleBytes: 96 * 1024,
+  concurrency: 4,
+  userAgent: "dsh-windows-mcp-index-probe",
+});
+
+/** No mirror describes itself in a way we can show; this is the fallback label. */
+export function mirrorById(id, candidates = MIRROR_CANDIDATES) {
+  return candidates.find((entry) => entry.id === id) ?? null;
+}
+
+/** Human line for the Plugins page: `USTC 中科大 · 1.7 MB/s`. */
+export function describeMirror(result) {
+  if (result === null || result === undefined) return "—";
+  if (result.ok !== true) return `${result.label} · 不可用`;
+  const speed = typeof result.speedBps === "number" ? result.speedBps : 0;
+  return `${result.label} · ${formatBytesPerSecond(speed)}`;
+}
+
+/** Bytes per second → `1.7 MB/s` / `820 KB/s`. */
+export function formatBytesPerSecond(bytesPerSecond) {
+  const value = Number(bytesPerSecond);
+  if (!Number.isFinite(value) || value <= 0) return "—";
+  if (value >= 1024 * 1024) return `${(value / (1024 * 1024)).toFixed(1)} MB/s`;
+  return `${Math.max(1, Math.round(value / 1024))} KB/s`;
+}
+
+/** `fetch` with a hard timeout; rejects with a readable message. */
+async function timedFetch(fetchImpl, url, init, timeoutMs) {
+  const options = { ...init, signal: AbortSignal.timeout(timeoutMs) };
+  try {
+    return await fetchImpl(url, options);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${message} (${url})`);
+  }
+}
+
+/** Probe one mirror: index latency, then a ranged wheel sample for throughput. */
+async function probeMirror(mirror, settings) {
+  const startedAt = Date.now();
+  const base = {
+    id: mirror.id,
+    label: mirror.label,
+    indexUrl: mirror.indexUrl,
+    official: mirror.official === true,
+  };
+  try {
+    const pageUrl = projectIndexUrl(mirror.indexUrl, settings.project);
+    const page = await timedFetch(
+      settings.fetchImpl,
+      pageUrl,
+      { headers: { accept: "text/html", "user-agent": settings.userAgent } },
+      settings.timeoutMs,
+    );
+    const indexMs = Date.now() - startedAt;
+    if (page?.ok !== true) throw new Error(`index answered HTTP ${page?.status ?? "?"}`);
+    const html = typeof page.text === "function" ? await page.text() : "";
+    const entries = parseIndex(html, pageUrl);
+    if (entries.length === 0) throw new Error("the index lists no windows-mcp files");
+    const wanted = settings.version === null || settings.version === undefined
+      ? latestStableEntry(entries)
+      : entryForVersion(entries, settings.version);
+    if (wanted === null) throw new Error(`version ${settings.version} is not on this mirror`);
+    const downloadStartedAt = Date.now();
+    const sample = await timedFetch(
+      settings.fetchImpl,
+      wanted.url,
+      {
+        headers: {
+          range: `bytes=0-${Math.max(0, settings.sampleBytes - 1)}`,
+          "user-agent": settings.userAgent,
+        },
+      },
+      settings.timeoutMs,
+    );
+    const status = sample?.status ?? 0;
+    if (status !== 200 && status !== 206) throw new Error(`wheel sample answered HTTP ${status}`);
+    const body = typeof sample.arrayBuffer === "function" ? new Uint8Array(await sample.arrayBuffer()) : new Uint8Array();
+    const downloadMs = Math.max(1, Date.now() - downloadStartedAt);
+    return {
+      ...base,
+      ok: true,
+      indexMs,
+      downloadMs,
+      bytes: body.byteLength,
+      speedBps: body.byteLength === 0 ? 0 : Math.round(body.byteLength / (downloadMs / 1000)),
+      version: wanted.version,
+      filename: wanted.filename,
+      error: null,
+    };
+  } catch (error) {
+    return {
+      ...base,
+      ok: false,
+      indexMs: null,
+      downloadMs: null,
+      bytes: 0,
+      speedBps: 0,
+      version: null,
+      filename: null,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Probe every candidate concurrently (bounded), then rank the survivors.
+ * @returns `{ probedAt, results, ranked, best, project, version }`.
+ */
+export async function probeMirrors(options = {}) {
+  const settings = {
+    ...PROBE_DEFAULTS,
+    ...options,
+    fetchImpl: options.fetchImpl ?? globalThis.fetch,
+    candidates: Array.isArray(options.candidates) ? options.candidates : MIRROR_CANDIDATES,
+  };
+  if (typeof settings.fetchImpl !== "function") {
+    return { probedAt: new Date().toISOString(), results: [], ranked: [], best: null, project: settings.project, version: settings.version, error: "no fetch implementation" };
+  }
+  const queue = settings.candidates.slice();
+  const results = [];
+  const workerCount = Math.max(1, Math.min(settings.concurrency, queue.length));
+  const workers = Array.from({ length: workerCount }, async () => {
+    while (queue.length > 0) {
+      const mirror = queue.shift();
+      if (mirror === undefined) return;
+      results.push(await probeMirror(mirror, settings));
+    }
+  });
+  await Promise.all(workers);
+  const ranked = results
+    .filter((result) => result.ok === true)
+    .sort((left, right) => {
+      if (right.speedBps !== left.speedBps) return right.speedBps - left.speedBps;
+      return (left.indexMs ?? Number.MAX_SAFE_INTEGER) - (right.indexMs ?? Number.MAX_SAFE_INTEGER);
+    });
+  return {
+    probedAt: new Date().toISOString(),
+    results,
+    ranked: ranked.map((result) => result.id),
+    best: ranked[0] ?? null,
+    project: settings.project,
+    version: settings.version,
+  };
+}
+
+/**
+ * Read the full project index from one mirror: every file for every version.
+ * @returns `{ indexUrl, pageUrl, entries, versions, latest }` — `versions` is
+ *   newest-first and includes prereleases, `latest` is the newest stable one.
+ */
+export async function fetchProjectIndex(options = {}) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  const project = options.project ?? PROBE_DEFAULTS.project;
+  const indexUrl = options.indexUrl;
+  const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : PROBE_DEFAULTS.timeoutMs;
+  const userAgent = options.userAgent ?? PROBE_DEFAULTS.userAgent;
+  const pageUrl = projectIndexUrl(indexUrl, project);
+  const response = await timedFetch(fetchImpl, pageUrl, { headers: { accept: "text/html", "user-agent": userAgent } }, timeoutMs);
+  if (response?.ok !== true) throw new Error(`${indexUrl} answered HTTP ${response?.status ?? "?"}`);
+  const entries = parseIndex(typeof response.text === "function" ? await response.text() : "", pageUrl);
+  const versions = [...new Set(entries.map((entry) => entry.version))];
+  return { indexUrl, pageUrl, entries, versions, latest: latestStableVersion(versions) };
+}
+
+/** Mirrors in the order an install should try them: ranked first, official last. */
+export function mirrorOrder(probe, candidates = MIRROR_CANDIDATES) {  const seen = new Set();
+  const order = [];
+  for (const id of Array.isArray(probe?.ranked) ? probe.ranked : []) {
+    const mirror = mirrorById(id, candidates);
+    if (mirror !== null && !seen.has(mirror.id)) {
+      seen.add(mirror.id);
+      order.push(mirror);
+    }
+  }
+  for (const mirror of candidates) {
+    if (mirror.official === true && !seen.has(mirror.id)) {
+      seen.add(mirror.id);
+      order.push(mirror);
+    }
+  }
+  for (const mirror of candidates) {
+    if (!seen.has(mirror.id)) {
+      seen.add(mirror.id);
+      order.push(mirror);
+    }
+  }
+  return order;
+}
+
+/** The mirror an install should try first, or null when nothing was probed. */
+export function preferredMirror(probe, candidates = MIRROR_CANDIDATES) {
+  return mirrorOrder(probe, candidates)[0] ?? null;
+}

package/lib/pypi.js

@@ -0,0 +1,171 @@
+/**
+ * dsh-windows-mcp — PyPI index parsing and version maths (host side).
+ *
+ * The upstream program (`windows-mcp`) is published on PyPI, so the plugin needs
+ * two things that look like string processing but must be exactly right:
+ *
+ *   1. **Which versions exist, and which is the newest stable one?** — a PEP 503
+ *      `/simple/<project>/` page is plain HTML; this module parses it instead of
+ *      the JSON API, because some mirrors do not serve the JSON API at all and
+ *      the simple page is the one file every mirror does serve.
+ *   2. **Is 0.9.0 newer than 0.8.10?** — no `semver` dependency here, so the
+ *      comparison is written down once and tested: numeric component-wise, with
+ *      a stable release sorting above a pre-release of the same core.
+ *
+ * Everything is pure: no I/O, no network, no throwing. A malformed page simply
+ * yields fewer entries.
+ */
+
+/** Path of the project's index on a mirror, e.g. `https://…/simple/windows-mcp/`. */
+export function projectIndexUrl(indexUrl, project) {
+  return `${String(indexUrl ?? "").replace(/\/+$/u, "")}/${String(project ?? "").replace(/^\/+/u, "")}/`;
+}
+
+/**
+ * Numeric core of a version plus whatever trails it.
+ * @returns `{ parts: number[], rest: string }` or null.
+ */
+export function versionParts(version) {
+  const match = /^v?(\d+(?:\.\d+)*)(.*)$/u.exec(String(version ?? "").trim());
+  if (match === null) return null;
+  const parts = match[1].split(".").map((piece) => Number.parseInt(piece, 10));
+  if (parts.some((piece) => !Number.isFinite(piece))) return null;
+  return { parts, rest: match[2].trim() };
+}
+
+/** A release without a pre-release/dev/post marker: `0.8.8`, not `0.9.0rc1`. */
+export function isStableVersion(version) {
+  return /^\d+(?:\.\d+)*$/u.test(String(version ?? "").trim());
+}
+
+/**
+ * Compare two versions: -1, 0 or 1. Non-numeric strings fall back to a plain
+ * string compare so the caller still gets a total order.
+ */
+export function compareVersions(left, right) {
+  const a = versionParts(left);
+  const b = versionParts(right);
+  if (a === null || b === null) {
+    const x = String(left ?? "");
+    const y = String(right ?? "");
+    if (x === y) return 0;
+    return x < y ? -1 : 1;
+  }
+  const length = Math.max(a.parts.length, b.parts.length);
+  for (let index = 0; index < length; index += 1) {
+    const x = a.parts[index] ?? 0;
+    const y = b.parts[index] ?? 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  // Same numeric core: a bare release beats a pre-release (`0.9.0` > `0.9.0rc1`).
+  const ax = a.rest === "" ? 1 : 0;
+  const bx = b.rest === "" ? 1 : 0;
+  if (ax === bx) return 0;
+  return ax < bx ? -1 : 1;
+}
+
+/** The newest stable version of a list of versions, or null. */
+export function latestStableVersion(versions) {
+  let best = null;
+  for (const version of Array.isArray(versions) ? versions : []) {
+    if (typeof version !== "string" || !isStableVersion(version)) continue;
+    if (best === null || compareVersions(version, best) > 0) best = version;
+  }
+  return best;
+}
+
+/**
+ * The upstream version a PyPI filename refers to, or null.
+ * Handles wheels (`windows_mcp-0.8.8-py3-none-any.whl`) and sdists
+ * (`windows_mcp-0.8.8.tar.gz`); the distribution name must be this project's.
+ */
+export function versionFromFilename(filename, project = "windows-mcp") {
+  let clean;
+  try {
+    clean = decodeURIComponent(String(filename ?? "").replace(/^.*\//u, ""));
+  } catch {
+    clean = String(filename ?? "").replace(/^.*\//u, "");
+  }
+  if (clean === "") return null;
+  const distribution = String(project ?? "windows-mcp").replace(/-/gu, "[_-]");
+  const name = new RegExp(`^${distribution}$`, "iu");
+  const lower = clean.toLowerCase();
+  if (lower.endsWith(".whl")) {
+    const parts = clean.slice(0, -".whl".length).split("-");
+    if (parts.length < 2 || !name.test(parts[0])) return null;
+    return parts[1] === "" ? null : parts[1];
+  }
+  if (lower.endsWith(".tar.gz")) {
+    const parts = clean.slice(0, -".tar.gz".length).split("-");
+    if (parts.length < 2) return null;
+    if (!name.test(parts.slice(0, -1).join("-"))) return null;
+    return parts[parts.length - 1] === "" ? null : parts[parts.length - 1];
+  }
+  return null;
+}
+
+/**
+ * Parse a PEP 503 simple index page into entries, newest first.
+ * @param html - page body.
+ * @param pageUrl - absolute URL the page was served from (relative hrefs resolve against it).
+ * @returns `[{ filename, version, url, stable, yanked }]`.
+ */
+export function parseIndex(html, pageUrl) {
+  const entries = [];
+  const anchor = /<a\b[^>]*>/giu;
+  const body = String(html ?? "");
+  let match;
+  while ((match = anchor.exec(body)) !== null) {
+    const tag = match[0];
+    const href = /href\s*=\s*"([^"]+)"/iu.exec(tag);
+    if (href === null) continue;
+    const target = String(href[1]);
+    // PEP 503 links may carry a `#sha256=…` fragment (and occasionally a query);
+    // the *file name* is the path's last segment, never the fragment.
+    const rawPath = target.split("#")[0].split("?")[0];
+    let filename = rawPath.replace(/^.*\//u, "");
+    try {
+      filename = decodeURIComponent(filename);
+    } catch {
+      /* keep it percent-encoded then */
+    }
+    const version = versionFromFilename(filename);
+    if (version === null) continue;
+    let url = target;
+    try {
+      url = new URL(target, pageUrl).href;
+    } catch {
+      /* keep the raw href; the caller reports a failure */
+    }
+    entries.push({
+      filename,
+      version,
+      url,
+      stable: isStableVersion(version),
+      yanked: /data-yanked\s*=/iu.test(tag),
+    });
+  }
+  return entries.sort((left, right) => compareVersions(right.version, left.version));
+}
+
+/** Newest stable entry of a parsed index, or null. */
+export function latestStableEntry(entries) {
+  let best = null;
+  for (const entry of Array.isArray(entries) ? entries : []) {
+    if (entry?.stable !== true || entry?.yanked === true) continue;
+    if (best === null || compareVersions(entry.version, best.version) > 0) best = entry;
+  }
+  return best;
+}
+
+/** A wheel for `version` if the index has one, else the sdist, else any entry. */
+export function entryForVersion(entries, version) {
+  if (!Array.isArray(entries)) return null;
+  const matching = entries.filter((entry) => entry?.version === version && entry?.yanked !== true);
+  if (matching.length === 0) return null;
+  return (
+    matching.find((entry) => entry.filename.toLowerCase().endsWith(".whl")) ??
+    matching.find((entry) => entry.filename.toLowerCase().endsWith(".tar.gz")) ??
+    matching[0]
+  );
+}