ictrp-mcp-server 0.1.0

package/dist/runtime/bootstrap.js

@@ -0,0 +1,350 @@
+/**
+ * Runtime self-setup: create the private venv and install the vendored package.
+ *
+ * This exists because **a packaged desktop application does not run npm's
+ * `postinstall`**. A dmg or an exe is a copied directory tree; npm lifecycle
+ * scripts ran on the developer's machine, not on the user's. Anything the
+ * package needs at runtime must therefore be able to set itself up on first
+ * use, at runtime, with visible progress and a definite failure mode.
+ *
+ * Two rules govern the whole module:
+ *
+ * 1. **Never roll back a completed step.** Steps are ordered cheapest-first
+ *    (venv, then dependencies, then anything large). Re-running is meant to
+ *    resume, so a failure late in the sequence does not throw away work that
+ *    succeeded earlier.
+ *
+ * 2. **A step that did not run is not a step that failed.** `skipped` is
+ *    reported as its own outcome so the operator can tell "already fine" from
+ *    "we installed it just now" from "we tried and it broke".
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { packageRoot, venvDir, venvPython, PROBE_TIMEOUT_MS } from "./env-probe.js";
+/**
+ * PyPI mirrors, most-likely-to-work first for the users this ships to.
+ *
+ * The fallback chain is not a nicety. A mirror can fail in a way that looks
+ * exactly like "this package does not exist" -- notably a 403 on a modern pip
+ * user-agent surfaces as `from versions: none`, which sends the operator
+ * hunting for a typo instead of a mirror problem. Trying the next mirror turns
+ * that misdiagnosis into a non-event.
+ */
+export const PYPI_MIRRORS = {
+    aliyun: "https://mirrors.aliyun.com/pypi/simple",
+    tencent: "https://mirrors.cloud.tencent.com/pypi/simple",
+    tsinghua: "https://pypi.tuna.tsinghua.edu.cn/simple",
+    official: "https://pypi.org/simple",
+};
+/**
+ * Build the mirror order: the preferred mirror first, then everything else
+ * except the official index, then the official index last as the backstop.
+ *
+ * `official` is pinned last on purpose. It is the most correct source and the
+ * slowest / most-blocked from the networks this is expected to run on, so it
+ * is the fallback rather than the default.
+ */
+export function mirrorChain(preferred) {
+    const chain = [];
+    const seen = new Set();
+    const push = (name, url) => {
+        const key = url.replace(/\/+$/, "");
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        chain.push({ name, url });
+    };
+    const pref = preferred ?? process.env.ICTRP_PIP_MIRROR ?? "aliyun";
+    if (pref && pref !== "official") {
+        // A raw URL is accepted, so an operator can point at an internal mirror.
+        if (PYPI_MIRRORS[pref])
+            push(pref, PYPI_MIRRORS[pref]);
+        else if (/^https?:\/\//.test(pref))
+            push(pref, pref);
+    }
+    for (const [name, url] of Object.entries(PYPI_MIRRORS)) {
+        if (name === "official")
+            continue;
+        push(name, url);
+    }
+    push("official", PYPI_MIRRORS["official"]);
+    return chain;
+}
+/**
+ * Run a child process, streaming its output to `onLine`.
+ *
+ * Exit codes follow the convention the installer relies on:
+ *   124 -- the step timed out and was killed
+ *   130 -- the run was aborted by the caller
+ *   127 -- the executable could not be spawned at all
+ */
+export function execStreaming(cmd, args, opts = {}) {
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        let timedOut = false;
+        const child = spawn(cmd, args, {
+            cwd: opts.cwd ?? packageRoot(),
+            windowsHide: true,
+            env: {
+                ...process.env,
+                PYTHONUNBUFFERED: "1",
+                PIP_DISABLE_PIP_VERSION_CHECK: "1",
+            },
+        });
+        const timer = opts.timeoutMs
+            ? setTimeout(() => {
+                timedOut = true;
+                child.kill("SIGKILL");
+            }, opts.timeoutMs)
+            : undefined;
+        const onAbort = () => child.kill("SIGKILL");
+        opts.signal?.addEventListener("abort", onAbort, { once: true });
+        const finish = (code, extra = "") => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            opts.signal?.removeEventListener("abort", onAbort);
+            resolve({ code, stdout, stderr: stderr + extra });
+        };
+        const feed = (chunk, into) => {
+            const text = chunk.toString("utf8");
+            if (into === "out")
+                stdout += text;
+            else
+                stderr += text;
+            if (opts.onLine) {
+                // pip redraws its progress bar with carriage returns, so lines must be
+                // split on both.
+                for (const line of text.split(/[\r\n]+/)) {
+                    const trimmed = line.trim();
+                    if (trimmed)
+                        opts.onLine(trimmed);
+                }
+            }
+        };
+        child.stdout?.on("data", (c) => feed(c, "out"));
+        child.stderr?.on("data", (c) => feed(c, "err"));
+        child.on("error", (err) => {
+            stderr += `${err.message}\n`;
+            finish(127);
+        });
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            if (timedOut)
+                return finish(124);
+            if (opts.signal?.aborted)
+                return finish(130);
+            finish(code ?? 0);
+        });
+    });
+}
+/** Find a usable system Python, newest acceptable version first. */
+export async function discoverPython() {
+    const candidates = process.platform === "win32"
+        ? ["py", "python3", "python"]
+        : ["python3.13", "python3.12", "python3.11", "python3.10", "python3"];
+    for (const cmd of candidates) {
+        const args = cmd === "py" ? ["-3", "--version"] : ["--version"];
+        const res = await execStreaming(cmd, args, { timeoutMs: 10_000 });
+        if (res.code !== 0)
+            continue;
+        const text = `${res.stdout}${res.stderr}`.trim();
+        const match = /(\d+)\.(\d+)/.exec(text);
+        if (!match)
+            continue;
+        const major = Number(match[1]);
+        const minor = Number(match[2]);
+        if (major > 3 || (major === 3 && minor >= 10)) {
+            return { cmd, version: `${major}.${minor}` };
+        }
+    }
+    return undefined;
+}
+/**
+ * Create the private virtual environment.
+ *
+ * The venv lives beside the package by default but is relocatable via
+ * `ICTRP_VENV`, which matters when the package directory is read-only (an
+ * asar archive) or shared between users.
+ */
+async function ensureVenv(onProgress) {
+    const step = "venv";
+    const dir = venvDir();
+    const python = venvPython();
+    if (existsSync(python)) {
+        const res = await execStreaming(python, ["--version"], { timeoutMs: PROBE_TIMEOUT_MS });
+        if (res.code === 0) {
+            return {
+                step,
+                outcome: "skipped",
+                message: `venv already usable (${`${res.stdout}${res.stderr}`.trim()})`,
+                attempts: 0,
+            };
+        }
+        // A venv that will not run is worse than none: it will shadow a good
+        // interpreter and produce confusing errors. Remove and rebuild.
+        onProgress({ step, message: "现有的虚拟环境无法运行，正在重建" });
+    }
+    const found = await discoverPython();
+    if (!found) {
+        return {
+            step,
+            outcome: "failed",
+            message: "no Python 3.10+ interpreter found on PATH",
+            attempts: 0,
+        };
+    }
+    onProgress({ step, message: `使用 ${found.cmd} (python ${found.version}) 创建虚拟环境` });
+    mkdirSync(path.dirname(dir), { recursive: true });
+    const args = ["-m", "venv", dir];
+    const res = await execStreaming(found.cmd, args, {
+        timeoutMs: 5 * 60 * 1000,
+        onLine: (line) => onProgress({ step, message: line }),
+    });
+    if (res.code === 0 && existsSync(python)) {
+        return { step, outcome: "ok", message: `created ${dir}`, attempts: 1 };
+    }
+    return {
+        step,
+        outcome: "failed",
+        message: `venv creation failed (exit ${res.code}): ${res.stderr.trim().slice(-400)}`,
+        attempts: 1,
+    };
+}
+/**
+ * Install the vendored package into the venv, trying each mirror in turn.
+ *
+ * The package is installed from the repository root (`.[offline]` style extras
+ * are not needed -- the runtime deps are the base install). When the source
+ * tree is not present, the pinned PyPI distribution is used instead.
+ */
+async function installDeps(preferred, onProgress) {
+    const step = "deps";
+    const python = venvPython();
+    const chain = mirrorChain(preferred);
+    const triedMirrors = [];
+    // Idempotence check first: if everything imports, do not touch the network.
+    const probe = "import importlib.util as u;" +
+        "print(all(u.find_spec(m) is not None for m in ['mcp','httpx','pydantic']))";
+    const check = await execStreaming(python, ["-c", probe], { timeoutMs: PROBE_TIMEOUT_MS });
+    if (check.code === 0 && check.stdout.trim() === "True") {
+        return { step, outcome: "skipped", message: "dependencies already installed", attempts: 0 };
+    }
+    // Where does the Python source live?
+    //
+    // Three layouts, in the order they should be preferred:
+    //
+    //   1. a checkout -- the npm package sits *inside* the Python project, so
+    //      the package root has no pyproject.toml while its parent does;
+    //   2. a published npm install -- `sidecar/vendor/ictrp_mcp` carries the
+    //      source, so the dependency is installed from the tarball itself. This
+    //      is what makes the package self-contained: it does not matter whether
+    //      a matching release exists on PyPI, and the Python that runs is
+    //      always the same commit as the JavaScript around it.
+    //   3. nothing local -- fall back to the PyPI distribution.
+    //
+    // The ordering matters. Trying PyPI before the vendored copy would make a
+    // published install depend on a release that may not exist yet, which
+    // surfaces as the thoroughly unhelpful "from versions: none".
+    //
+    // Note this searches the *code* location, not ICTRP_HOME. Looking for Python
+    // source under a desktop host's private data directory could only ever turn
+    // up someone else's file.
+    const root = packageRoot();
+    const vendored = path.join(root, "sidecar", "vendor");
+    const localSource = [root, path.resolve(root, "..")].find((dir) => existsSync(path.join(dir, "pyproject.toml")));
+    let target;
+    let targetLabel;
+    if (localSource) {
+        target = localSource;
+        targetLabel = "本地源码";
+    }
+    else if (existsSync(path.join(vendored, "ictrp_mcp"))) {
+        target = vendored;
+        targetLabel = "包内 vendor";
+    }
+    else {
+        target = "ictrp-mcp-service";
+        targetLabel = "PyPI";
+    }
+    onProgress({ step, message: `安装来源：${targetLabel}` });
+    // Upgrade pip first, but never let it block the install: an old pip that can
+    // still resolve packages is fine, and a mirror that cannot serve pip is not
+    // a reason to give up on the package itself.
+    onProgress({ step, message: `升级 pip（${chain[0].name}）` });
+    await execStreaming(python, ["-m", "pip", "install", "--upgrade", "pip", "-i", chain[0].url], {
+        timeoutMs: 5 * 60 * 1000,
+    });
+    for (const mirror of chain) {
+        triedMirrors.push(mirror.name);
+        onProgress({ step, message: `安装依赖（${mirror.name}）`, percent: undefined });
+        const args = ["-m", "pip", "install", "-i", mirror.url, target];
+        const res = await execStreaming(python, args, {
+            timeoutMs: 30 * 60 * 1000,
+            onLine: (line) => {
+                const pct = /(\d{1,3})%/.exec(line);
+                onProgress({
+                    step,
+                    message: line,
+                    percent: pct ? Number(pct[1]) : undefined,
+                });
+            },
+        });
+        if (res.code === 0) {
+            const fellBack = triedMirrors.length > 1;
+            return {
+                step,
+                outcome: "ok",
+                message: fellBack
+                    ? `前 ${triedMirrors.length - 1} 个镜像失败后回退成功：${mirror.name}`
+                    : `installed via ${mirror.name}`,
+                attempts: triedMirrors.length,
+                triedMirrors,
+            };
+        }
+        onProgress({ step, message: `镜像 ${mirror.name} 失败（exit ${res.code}），尝试下一个` });
+    }
+    return {
+        step,
+        outcome: "failed",
+        message: `all ${chain.length} mirrors failed`,
+        attempts: triedMirrors.length,
+        triedMirrors,
+    };
+}
+/**
+ * Bring the environment to a usable state.
+ *
+ * Returns rather than throws: the caller (`setup` CLI, or the MCP layer's
+ * lazy bootstrap) needs the step list to report *what* went wrong.
+ */
+export async function bootstrapEnvironment(opts = {}) {
+    const onProgress = opts.onProgress ?? (() => { });
+    const steps = [];
+    const errors = [];
+    const venv = await ensureVenv(onProgress);
+    steps.push(venv);
+    if (venv.outcome === "failed") {
+        errors.push(`虚拟环境创建失败：${venv.message}`);
+        // Everything downstream needs the venv; stopping here is honest.
+        return { ok: false, steps, errors };
+    }
+    if (opts.signal?.aborted) {
+        errors.push("已取消");
+        return { ok: false, steps, errors };
+    }
+    const deps = await installDeps(opts.mirror, onProgress);
+    steps.push(deps);
+    if (deps.outcome === "failed") {
+        errors.push(`依赖安装失败：${deps.message}`);
+        return { ok: false, steps, errors };
+    }
+    return { ok: true, steps, errors };
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/runtime/bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../../src/runtime/bootstrap.ts"],"names":[],"mappings":"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"}

package/dist/runtime/env-probe.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Read-only environment inspection.
+ *
+ * This module never writes to disk and never starts a process that can modify
+ * state. It answers one question -- "could this package do its job right now?"
+ * -- and it answers it without side effects, because it is called by installers,
+ * by `doctor`, and by an MCP tool that a language model may invoke at any time.
+ *
+ * Three separate readiness notions exist here and they are deliberately not the
+ * same thing:
+ *
+ *   - `canRunOnline`  -- a venv with the vendored package installed exists, so
+ *                        a live ICTRP search is possible.
+ *   - `canRunOffline` -- a bundled snapshot is present, so *something* can be
+ *                        answered with no network and no Python at all... almost.
+ *                        In practice the offline path also goes through Python,
+ *                        so this is reported for operator information.
+ *   - `ready`         -- what a client should check before enabling the server.
+ *
+ * Collapsing them into one boolean would make `doctor` unable to say *why* an
+ * installation is not usable, which is the only reason it exists.
+ */
+/** Minimum Python the vendored package supports. Mirrors pyproject.toml. */
+export declare const MIN_PYTHON: readonly [number, number];
+/**
+ * Keep this list in sync with the `dependencies` in the Python package's
+ * pyproject.toml. A module missing here is a module the sidecar will fail to
+ * import at runtime, with a much worse error message.
+ */
+export declare const PYTHON_MODULES: readonly string[];
+/** Per-command timeout for the helper process spawns below. */
+export declare const PROBE_TIMEOUT_MS = 8000;
+/** How long a computed report stays fresh before it is recomputed. */
+export declare const PROBE_TTL_MS = 30000;
+export type CheckStatus = "ok" | "missing" | "outdated" | "error" | "unknown";
+export interface CheckResult {
+    status: CheckStatus;
+    detail: string;
+    hint?: string;
+}
+export interface EnvCheck {
+    status: CheckStatus;
+    detail: string;
+    hint?: string;
+}
+export interface EnvReport {
+    root: string;
+    platform: string;
+    node: EnvCheck;
+    venv: EnvCheck;
+    pythonVersion: EnvCheck;
+    pythonDeps: EnvCheck;
+    sidecarScript: EnvCheck;
+    sidecar: EnvCheck;
+    /** True when a private venv with the vendored package is usable. */
+    canRunOnline: boolean;
+    /** True when the sidecar process is answering right now. */
+    sidecarRunning: boolean;
+    ready: boolean;
+    summary: string;
+    actions: string[];
+}
+/**
+ * Where the *code* lives: the installed package directory, containing
+ * `sidecar/` and `package.json`.
+ *
+ * This is deliberately NOT affected by `ICTRP_HOME`. Code location and
+ * writable-state location are different questions, and conflating them breaks
+ * the packaged case: an Electron host sets `ICTRP_HOME` to its private data
+ * directory, and if that also redirected this lookup the sidecar script would
+ * be searched for inside an empty data directory. It would not be found, and
+ * the failure would present as "the package is incomplete" -- pointing at the
+ * wrong problem entirely.
+ */
+export declare function packageRoot(): string;
+/**
+ * Where writable state goes: virtualenv, snapshots, scratch files.
+ *
+ * Overridable with `ICTRP_HOME`, which the desktop integration sets to the
+ * application's private data directory so that a read-only package directory
+ * (an asar archive, a system-path global install) is never written to.
+ * Defaults to the package root, which is correct for a normal npm install.
+ */
+export declare function stateRoot(): string;
+/**
+ * @deprecated Use {@link packageRoot} for code or {@link stateRoot} for
+ * writable state. Kept because it is re-exported from the package entry point;
+ * it resolves to the code location, which is the answer most callers wanted.
+ */
+export declare function projectRoot(): string;
+export declare function venvDir(): string;
+export declare function venvPython(): string;
+export declare function sidecarScript(): string;
+/** Where the Node layer caches materialized sets between sidecar restarts. */
+export declare function nodeCacheDir(): string;
+export declare function sidecarBaseUrl(): string;
+export declare function invalidateEnvReport(): void;
+/**
+ * Build the environment report.
+ *
+ * Concurrent calls share one in-flight probe: an installer that fires several
+ * checks at once, or a client that renders several status rows, must not spawn
+ * a dozen Python processes.
+ */
+export declare function getEnvReport(force?: boolean): Promise<EnvReport>;
+export declare function formatEnvReport(report: EnvReport): string;
+/** True when a path exists and is writable, used by the installer. */
+export declare function isWritable(dir: string): boolean;