@dongfangw/study-kit 0.0.0-stage → 0.1.0

package/lib/slidevEnv.js

@@ -0,0 +1,702 @@
+/**
+ * Slidev 课件环境的「体检 + 修复」。
+ *
+ * 背景：课件能否放映取决于宿主机环境（Node/npm、@slidev/cli、主题依赖），
+ * 而这些都不在仓库里。过去只有一句「未找到 slidev CLI」，用户看到的是永远转圈的
+ * 「正在准备 Slidev 课件…」，既不知道该装什么，也不知道装到哪里。
+ *
+ * 本模块提供三件事：
+ *   1. checkSlidevEnv()       —— 逐项体检（Node / npm / CLI / 版本 / 主题 / 课件包），
+ *                               返回给人看的结论 + 给机器看的修复动作（含将执行的命令）；
+ *   2. consentToken(action)   —— 把「动作 = 命令」签成一次性票据：客户端必须先把动作
+ *                               展示给用户并取得同意，再带票据回来，服务端才动手；
+ *   3. runEnvFix()            —— 真正执行安装（npm/pnpm），带超时与输出采集，
+ *                               成功后清空体检缓存与 CLI 解析缓存并复检。
+ *
+ * 安全边界：安装写入的路径全部在响应里明示；全局安装（`npm i -g`）会改宿主机环境，
+ * 因此必须经用户同意（票据 + confirm=true）才执行；无票据一律 403/400，绝不「顺手装」。
+ */
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { closeSync, existsSync, mkdtempSync, openSync, readFileSync, rmSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { resetSlidevBinCache, resolveSlidevBin, SLIDEV_CLI_ENTRY } from './slidevBin.js';
+// ---------------------------------------------------------------------------
+// 常量
+// ---------------------------------------------------------------------------
+/** 本仓库课件实测验证过的构建链锚点（lint W10 的推荐口径）。 */
+export const SLIDEV_ANCHOR_VERSION = '52.19.1';
+/** 主题 package.json 声明的 slidev 下限（engines.slidev >=52.1.0）；低于它才判「过旧不可用」。 */
+export const SLIDEV_MIN_SUPPORTED = '52.1.0';
+/** 安装建议（与 make-ppt / review-ppt 技能中的版本口径一致）。 */
+export const SLIDEV_RECOMMENDED_RANGE = '^52.19';
+/** 一键安装的 npm 包规格。 */
+const SLIDEV_INSTALL_SPEC = `@slidev/cli@${SLIDEV_RECOMMENDED_RANGE}`;
+/** Node 下限（@slidev/cli 52 的 engines 要求）。 */
+const NODE_MIN_MAJOR = 20;
+/** 体检结果缓存时长（避免每次打开课件都跑子进程）。 */
+const PROBE_TTL_MS = 30_000;
+/** 版本探测子进程超时。 */
+const VERSION_TIMEOUT_MS = 30_000;
+/** 安装子进程超时（全局装 CLI 视网络可能需要几分钟；@slidev/cli 依赖较重，10 分钟偏紧）。 */
+const INSTALL_TIMEOUT_MS = 20 * 60_000;
+/** 同意票据有效期。 */
+const TOKEN_TTL_MS = 10 * 60_000;
+/** 安装输出回传上限（字符）。 */
+const MAX_INSTALL_OUTPUT = 20_000;
+/** 票据签名密钥：进程随机生成，重启即失效（不需要跨重启有效）。 */
+const SECRET = randomBytes(32);
+/**
+ * 运行子进程并采集合并输出（超时杀进程；永不 reject，错误落在返回值里）。
+ *
+ * 输出走**临时日志文件**而不是管道：① 避免管道背压拖慢安装；② 某些受限/沙箱环境
+ * 禁止创建命名管道，piped stdio 会直接 EPERM —— 落文件在这些环境里仍能工作。
+ */
+function runCommand(cmd, args, opts) {
+    return new Promise((resolve) => {
+        let dir = null;
+        let fd = null;
+        /** 超时被我们主动杀掉（区别于进程自己以非 0 码退出）。 */
+        let timedOut = false;
+        try {
+            dir = mkdtempSync(path.join(os.tmpdir(), 'aero-envrun-'));
+            const logFile = path.join(dir, 'out.log');
+            fd = openSync(logFile, 'w');
+            let child;
+            try {
+                child = spawn(cmd, args, {
+                    ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+                    windowsHide: true,
+                    env: { ...process.env, NO_COLOR: '1', FORCE_COLOR: '0', GIT_TERMINAL_PROMPT: '0', npm_config_yes: 'true' },
+                    stdio: ['ignore', fd, fd],
+                });
+            }
+            catch (e) {
+                closeSync(fd);
+                fd = null;
+                rmSync(dir, { recursive: true, force: true });
+                resolve({ code: null, out: '', error: e instanceof Error ? e.message : String(e) });
+                return;
+            }
+            const readLog = () => {
+                try {
+                    return readFileSync(logFile, 'utf8').slice(-MAX_INSTALL_OUTPUT);
+                }
+                catch {
+                    return '';
+                }
+            };
+            const cleanup = () => {
+                if (fd !== null) {
+                    try {
+                        closeSync(fd);
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                    fd = null;
+                }
+                if (dir !== null) {
+                    try {
+                        rmSync(dir, { recursive: true, force: true });
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                    dir = null;
+                }
+            };
+            const timer = setTimeout(() => {
+                timedOut = true;
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    /* ignore */
+                }
+            }, opts.timeoutMs);
+            child.on('error', (e) => {
+                clearTimeout(timer);
+                const out = readLog();
+                cleanup();
+                resolve({ code: null, out, error: e.message });
+            });
+            child.on('close', (code) => {
+                clearTimeout(timer);
+                const out = readLog();
+                cleanup();
+                // 超时被杀时 code 为 null：必须与「进程正常退出但退出码非 0」区分开，
+                // 否则界面只会显示一句无从下手的「安装进程退出码 null」。
+                // npm 在非 TTY 下不打印进度，超时被杀时输出很可能为空，故错误文案要自带解释。
+                resolve(timedOut
+                    ? { code, out, error: `安装超时：超过 ${Math.round(opts.timeoutMs / 60_000)} 分钟仍未结束，已终止进程。若网络较慢，可在终端手动执行 npm i -g @slidev/cli@^52.19 并观察输出。` }
+                    : { code, out });
+            });
+        }
+        catch (e) {
+            if (fd !== null) {
+                try {
+                    closeSync(fd);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            if (dir !== null)
+                rmSync(dir, { recursive: true, force: true });
+            resolve({ code: null, out: '', error: e instanceof Error ? e.message : String(e) });
+        }
+    });
+}
+/** 从任意命令输出中提取第一个 `x.y.z` 版本号。 */
+function parseVersion(text) {
+    const m = /(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?/.exec(text);
+    return m === null ? null : m[0];
+}
+/** 数字点分版本比较：a<b 返回 -1，相等 0，a>b 返回 1。 */
+function cmpVersion(a, b) {
+    const pa = a.split('-')[0].split('.').map((x) => Number.parseInt(x, 10) || 0);
+    const pb = b.split('-')[0].split('.').map((x) => Number.parseInt(x, 10) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return d < 0 ? -1 : 1;
+    }
+    return 0;
+}
+/** PATH 上是否存在某个命令（Windows 需带 .cmd/.exe 后缀）。 */
+function findOnPath(names) {
+    const exts = process.platform === 'win32' ? ['.cmd', '.exe', '.bat'] : [''];
+    for (const dir of (process.env.PATH ?? '').split(path.delimiter)) {
+        if (dir === '')
+            continue;
+        for (const name of names) {
+            for (const ext of exts) {
+                const cand = path.join(dir, name + ext);
+                if (existsSync(cand))
+                    return cand;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * 定位 npm 的 JS 入口（npm-cli.js）。
+ *
+ * 直接 `spawn('npm.cmd', …)` 在 Windows 上需要 shell 解析（对含空格/中文的路径很脆弱），
+ * 因此统一用 `node npm-cli.js` 执行；找不到 JS 入口时返回 null，由调用方回退到 shim。
+ */
+function resolveNpmJs() {
+    const nodeDir = path.dirname(process.execPath);
+    const candidates = [
+        path.join(nodeDir, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+        path.join(nodeDir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    ];
+    const shim = findOnPath(['npm']);
+    if (shim !== null) {
+        const shimDir = path.dirname(shim);
+        candidates.push(path.join(shimDir, 'node_modules', 'npm', 'bin', 'npm-cli.js'));
+        // pnpm 安装的 shim：<dir>/../npm/bin/npm-cli.js
+        candidates.push(path.join(shimDir, '..', 'npm', 'bin', 'npm-cli.js'));
+    }
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    return null;
+}
+/** 从已解析的 CLI 入口反推 @slidev/cli 包目录（<pkg>/bin/slidev.mjs → <pkg>）。 */
+function cliPackageDir(bin) {
+    let dir = path.dirname(bin);
+    for (let i = 0; i < 6; i++) {
+        const pj = path.join(dir, 'package.json');
+        if (existsSync(pj)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pj, 'utf8'));
+                if (pkg.name === '@slidev/cli' && typeof pkg.version === 'string')
+                    return dir;
+            }
+            catch {
+                /* 继续向上找 */
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+function dirHasEntries(dir) {
+    try {
+        return existsSync(dir) && statSync(dir).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** 读取主题 package.json 的 engines.slidev（用于版本口径提示）。 */
+function themeSlidevEngine(themeDir) {
+    try {
+        const pkg = JSON.parse(readFileSync(path.join(themeDir, 'package.json'), 'utf8'));
+        const v = pkg.engines?.slidev;
+        return typeof v === 'string' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 从 slides.md 头部读 theme 字段（与 slidev.ts 同口径，只读前 4KB）。 */
+function readThemeRef(slidesAbs) {
+    try {
+        const head = readFileSync(slidesAbs, 'utf8').slice(0, 4096);
+        const m = /^\s*theme:\s*(\S+)\s*$/m.exec(head);
+        if (m === null || m[1] === undefined)
+            return null;
+        return m[1].replace(/^['"]|['"]$/g, '');
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// 同意票据
+// ---------------------------------------------------------------------------
+function signToken(payload) {
+    return createHmac('sha256', SECRET).update(payload).digest('hex');
+}
+/** 为动作生成同意票据：绑定动作 id + 命令 + 签发时间，有效期 TOKEN_TTL_MS。 */
+function consentToken(actionId, command) {
+    const issuedAt = Date.now();
+    const payload = `${actionId}\n${command}\n${issuedAt}`;
+    return `${issuedAt}.${signToken(payload)}`;
+}
+/** 校验票据：签名不匹配 / 过期 / 与当前动作不符 → false。 */
+function verifyToken(token, actionId, command) {
+    const dot = token.indexOf('.');
+    if (dot <= 0)
+        return false;
+    const issuedAt = Number.parseInt(token.slice(0, dot), 10);
+    if (!Number.isFinite(issuedAt))
+        return false;
+    if (Math.abs(Date.now() - issuedAt) > TOKEN_TTL_MS)
+        return false;
+    const expect = Buffer.from(signToken(`${actionId}\n${command}\n${issuedAt}`), 'utf8');
+    const got = Buffer.from(token.slice(dot + 1), 'utf8');
+    if (expect.length !== got.length)
+        return false;
+    try {
+        return timingSafeEqual(expect, got);
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// 体检
+// ---------------------------------------------------------------------------
+function check(id, label, status, detail, hint = '', version = '') {
+    return { id, label, status, detail, hint, version };
+}
+/**
+ * 探测 @slidev/cli 版本。
+ *
+ * 优先读 CLI 入口所属包的 package.json（无子进程、最快，沙箱环境也适用）；
+ * 读不到时才回退到 `slidev --version`。
+ */
+async function probeCliVersion(bin) {
+    const pkgDir = cliPackageDir(bin);
+    if (pkgDir !== null) {
+        try {
+            const pkg = JSON.parse(readFileSync(path.join(pkgDir, 'package.json'), 'utf8'));
+            const v = typeof pkg.version === 'string' ? parseVersion(pkg.version) : null;
+            if (v !== null)
+                return { version: v, error: '' };
+        }
+        catch {
+            /* 回退到子进程探测 */
+        }
+    }
+    const r = await runCommand(process.execPath, [bin, '--version'], { timeoutMs: VERSION_TIMEOUT_MS });
+    if (r.error !== undefined)
+        return { version: null, error: r.error };
+    const v = parseVersion(r.out);
+    if (v !== null)
+        return { version: v, error: '' };
+    return {
+        version: null,
+        error: r.code === 0
+            ? '`slidev --version` 没有输出版本号（CLI 可能损坏或版本过旧）'
+            : `\`slidev --version\` 退出码 ${String(r.code)}：${r.out.trim().slice(-300) || '无输出'}`,
+    };
+}
+/**
+ * 环境体检。返回：
+ *   - checks：逐项结论（ok/warn/fail），前端直接渲染成清单；
+ *   - actions：可执行的修复动作（含将执行的命令与写入位置），需要用户同意；
+ *   - ready：课件构建链是否就绪（只有 fail 会影响它，warn 不影响）；
+ *   - summary：一句话结论（给 no-toolchain 提示复用）。
+ */
+export async function checkSlidevEnv(opts = {}) {
+    const checks = [];
+    const actions = [];
+    /** CLI 完全缺失或不可运行（会阻断构建）。 */
+    let cliBroken = false;
+    // ① Node：直接用宿主进程的版本（构建子进程与宿主同版本）。
+    const nodeVersion = process.versions.node;
+    const nodeMajor = Number.parseInt(nodeVersion.split('.')[0] ?? '0', 10) || 0;
+    if (nodeMajor >= NODE_MIN_MAJOR) {
+        checks.push(check('node', `Node.js（运行 Slidev 的运行时）`, 'ok', `v${nodeVersion}`, '', nodeVersion));
+    }
+    else {
+        checks.push(check('node', 'Node.js（运行 Slidev 的运行时）', 'fail', `v${nodeVersion} 过低（需要 ≥ ${NODE_MIN_MAJOR}）`, '请升级 Node.js 后重启 DSH。', nodeVersion));
+    }
+    // ② npm / pnpm：安装能力（缺失只影响「一键安装」，不影响已有 CLI 的构建）。
+    const npmPath = findOnPath(['npm']);
+    const pnpmPath = findOnPath(['pnpm']);
+    if (npmPath !== null) {
+        checks.push(check('npm', 'npm（用于安装依赖）', 'ok', npmPath, ''));
+    }
+    else if (pnpmPath !== null) {
+        checks.push(check('pnpm', 'npm / pnpm（用于安装依赖）', 'ok', `pnpm：${pnpmPath}`, ''));
+    }
+    else {
+        checks.push(check('npm', 'npm / pnpm（用于安装依赖）', 'fail', 'PATH 中未找到 npm 或 pnpm', '请安装 Node.js（自带 npm）后重启 DSH，否则无法自动安装缺失依赖。'));
+    }
+    // ③ @slidev/cli：路径 + 版本。
+    const bin = resolveSlidevBin();
+    let cliVersion = null;
+    /** 版本低于仓库锚点：只告警（实测仍能构建），不当作缺失。 */
+    let cliOutdated = false;
+    if (bin === null) {
+        cliBroken = true;
+        checks.push(check('slidev-cli', '@slidev/cli（课件构建器）', 'fail', '未找到 slidev 命令（PATH 与 AERO_SLIDEV_BIN 均无）', `安装：npm i -g ${SLIDEV_INSTALL_SPEC}；或设 AERO_SLIDEV_BIN 指向已有 CLI 入口。`));
+    }
+    else {
+        const probe = await probeCliVersion(bin);
+        cliVersion = probe.version;
+        if (probe.version === null) {
+            cliBroken = true;
+            checks.push(check('slidev-cli', '@slidev/cli（课件构建器）', 'fail', probe.error, `可尝试重装：npm i -g ${SLIDEV_INSTALL_SPEC}`, ''));
+        }
+        else if (cmpVersion(probe.version, SLIDEV_MIN_SUPPORTED) < 0) {
+            cliBroken = true;
+            checks.push(check('slidev-cli', '@slidev/cli（课件构建器）', 'fail', `v${probe.version} 过旧（低于主题声明的 slidev 下限 ${SLIDEV_MIN_SUPPORTED}）`, `请升级：npm i -g ${SLIDEV_INSTALL_SPEC}`, probe.version));
+        }
+        else if (cmpVersion(probe.version, SLIDEV_ANCHOR_VERSION) < 0) {
+            // 版本可用但低于仓库实测锚点：只提示，不阻断（本机 52.9.1 实测可正常构建）。
+            cliOutdated = true;
+            checks.push(check('slidev-cli', '@slidev/cli（课件构建器）', 'warn', `v${probe.version}（可构建；仓库实测锚点为 ${SLIDEV_ANCHOR_VERSION}，旧构建链在个别布局上可能有样式差异）`, `若遇到双栏/样式异常，可升级：npm i -g ${SLIDEV_INSTALL_SPEC}`, probe.version));
+        }
+        else {
+            checks.push(check('slidev-cli', '@slidev/cli（课件构建器）', 'ok', `v${probe.version}`, bin, probe.version));
+        }
+    }
+    // ④ 课件级：主题目录 + 主题依赖 + 课件本地 CLI。
+    let themeDir = null;
+    let deckDir = null;
+    if (opts.slidesAbs !== undefined && existsSync(opts.slidesAbs)) {
+        deckDir = path.dirname(opts.slidesAbs);
+        const themeRef = readThemeRef(opts.slidesAbs);
+        if (themeRef === null) {
+            checks.push(check('deck-theme', '课件主题声明', 'warn', 'slides.md 未声明 theme（将使用 Slidev 内置布局）', '', ''));
+        }
+        else if (!themeRef.startsWith('.')) {
+            checks.push(check('deck-theme', '课件主题声明', 'warn', `theme: ${themeRef}（npm 包名主题，插件暂只支持本地路径主题）`, '', ''));
+        }
+        else {
+            const abs = path.resolve(deckDir, themeRef);
+            if (!existsSync(path.join(abs, 'package.json'))) {
+                checks.push(check('deck-theme', '课件主题目录', 'fail', `主题目录不存在：${abs}`, '课件与主题需一起从仓库取全（teaching-case/mdPPT/theme-neversink）。'));
+            }
+            else {
+                themeDir = abs;
+                const engine = themeSlidevEngine(abs);
+                checks.push(check('deck-theme', '课件主题目录', 'ok', abs, engine !== null ? `主题要求 slidev ${engine}` : ''));
+                const nm = path.join(abs, 'node_modules');
+                if (dirHasEntries(nm) && existsSync(path.join(nm, '@slidev', 'types'))) {
+                    checks.push(check('deck-theme-deps', '主题依赖（node_modules/@slidev/types）', 'ok', nm, ''));
+                }
+                else {
+                    checks.push(check('deck-theme-deps', '主题依赖（node_modules/@slidev/types）', 'fail', dirHasEntries(nm) ? `${nm} 不完整（缺 @slidev/types）` : `${nm} 不存在`, `在主题目录执行 npm install：${abs}`));
+                }
+            }
+        }
+        const localCli = path.join(deckDir, 'node_modules', '@slidev', 'cli', SLIDEV_CLI_ENTRY);
+        if (existsSync(localCli)) {
+            checks.push(check('deck-local-cli', '课件本地 CLI（可选）', 'ok', localCli, ''));
+        }
+    }
+    // ---- 修复动作（不自动执行） ----
+    // 只有「完全找不到 CLI」或「CLI 过旧到已知不可用」才给安装动作；
+    // 版本低于锚点但仍能构建的情况只告警，不诱导用户改动全局环境。
+    if (cliBroken) {
+        actions.push({
+            id: 'install-cli-global',
+            label: `全局安装 ${SLIDEV_INSTALL_SPEC}`,
+            reason: bin === null ? '未找到 slidev 命令' : '现有 @slidev/cli 无法运行或版本过旧',
+            command: `npm i -g ${SLIDEV_INSTALL_SPEC}`,
+            cwd: '',
+            scope: 'global',
+            writes: '写入 npm 全局前缀（npm prefix -g 下的 node_modules 与 bin），影响本机所有项目',
+            token: '',
+            disabled: npmPath === null,
+            disabledReason: npmPath === null ? 'PATH 中未找到 npm，无法自动安装' : '',
+        });
+    }
+    else if (cliOutdated) {
+        actions.push({
+            id: 'install-cli-global',
+            label: `升级到 ${SLIDEV_INSTALL_SPEC}（可选）`,
+            reason: `当前 v${cliVersion ?? '?'} 可以构建，升级到仓库实测锚点可避免旧构建链的样式问题`,
+            command: `npm i -g ${SLIDEV_INSTALL_SPEC}`,
+            cwd: '',
+            scope: 'global',
+            writes: '写入 npm 全局前缀（npm prefix -g 下的 node_modules 与 bin），影响本机所有项目',
+            token: '',
+            disabled: npmPath === null,
+            disabledReason: npmPath === null ? 'PATH 中未找到 npm，无法自动安装' : '',
+        });
+    }
+    if (themeDir !== null) {
+        const nm = path.join(themeDir, 'node_modules');
+        if (!dirHasEntries(nm) || !existsSync(path.join(nm, '@slidev', 'types'))) {
+            actions.push({
+                id: 'install-theme-deps',
+                label: '安装课件主题依赖',
+                reason: '主题 node_modules 缺失或不完整，vite 构建会直接失败',
+                command: 'npm install',
+                cwd: themeDir,
+                scope: 'workspace',
+                writes: `写入 ${nm}（仅主题目录内，不动系统环境）`,
+                token: '',
+                disabled: npmPath === null,
+                disabledReason: npmPath === null ? 'PATH 中未找到 npm，无法自动安装' : '',
+            });
+        }
+    }
+    const failed = checks.filter((c) => c.status === 'fail');
+    const ready = !failed.some((c) => c.id === 'node' || c.id === 'slidev-cli' || c.id === 'deck-theme' || c.id === 'deck-theme-deps');
+    const summary = ready
+        ? (cliVersion !== null ? `环境就绪（@slidev/cli v${cliVersion}）` : '环境就绪')
+        : failed.map((c) => c.label.split('（')[0] + '：' + c.detail).join('；');
+    return {
+        ok: true,
+        ready,
+        platform: process.platform,
+        nodeVersion,
+        checks,
+        actions: actions.map((a) => ({ ...a, token: a.disabled ? '' : consentToken(a.id, `${a.command}\n${a.cwd}`) })),
+        summary,
+        probedAt: Date.now(),
+    };
+}
+// ---------------------------------------------------------------------------
+// 体检缓存（meta 路由也要用，避免重复跑子进程）
+// ---------------------------------------------------------------------------
+let cachedReport = null;
+/** 缓存对应的课件（主题/依赖检查是课件级的，换课件必须重探，否则会张冠李戴）。 */
+let cachedFor = null;
+/** 重复请求合并成一次探测。 */
+let inflight = null;
+/** 体检（带 TTL 缓存；仅同一课件复用）。force=true 强制重新探测。 */
+export async function getSlidevEnv(opts = {}, force = false) {
+    const key = opts.slidesAbs ?? '';
+    if (!force && cachedReport !== null && cachedFor === key && Date.now() - cachedReport.probedAt < PROBE_TTL_MS)
+        return cachedReport;
+    if (inflight !== null)
+        return inflight;
+    inflight = checkSlidevEnv(opts)
+        .then((r) => {
+        cachedReport = r;
+        cachedFor = key;
+        return r;
+    })
+        .finally(() => {
+        inflight = null;
+    });
+    return inflight;
+}
+/** 清空体检缓存（安装完成后调用）。 */
+export function resetSlidevEnvCache() {
+    cachedReport = null;
+    cachedFor = null;
+}
+// ---------------------------------------------------------------------------
+// 安装执行
+// ---------------------------------------------------------------------------
+/** 当前是否有安装在进行（一次只允许一个，避免并发写 npm 全局目录）。 */
+let install = { running: false, actionId: '', startedAt: 0, finishedAt: 0, output: '', code: null, error: '' };
+export function currentInstallState() {
+    return install;
+}
+/**
+ * 执行一个修复动作。必须带合法票据且 confirm=true，否则拒绝——
+ * 服务端从不在用户未同意的情况下改动环境。
+ */
+export async function runEnvFix(opts) {
+    if (!opts.confirm)
+        return { ok: false, code: 400, error: '未确认：安装需要用户在界面中明确同意后才能执行。' };
+    if (install.running)
+        return { ok: false, code: 409, error: `已有安装任务在执行（${install.actionId}），请等它结束。` };
+    // 用「当前环境」重建动作清单来校验票据：票据绑定动作 id + 命令，避免被构造任意命令。
+    const report = await checkSlidevEnv({ slidesAbs: opts.slidesAbs });
+    const action = report.actions.find((a) => a.id === opts.actionId);
+    if (action === undefined)
+        return { ok: false, code: 404, error: `未知或当前不再需要的修复动作：${opts.actionId}（环境可能已变化，请刷新体检结果）。` };
+    if (action.disabled)
+        return { ok: false, code: 400, error: action.disabledReason !== '' ? action.disabledReason : '该动作当前不可执行。' };
+    if (!verifyToken(opts.token, action.id, `${action.command}\n${action.cwd}`)) {
+        return { ok: false, code: 403, error: '安装票据无效或已过期：请刷新体检结果并重新确认。' };
+    }
+    const npmPath = findOnPath(['npm']);
+    if (npmPath === null)
+        return { ok: false, code: 400, error: 'PATH 中未找到 npm，无法自动安装。请手动执行面板中显示的命令。' };
+    const npmJs = resolveNpmJs();
+    const npmCmd = npmJs === null ? npmPath : process.execPath;
+    const npmArgs = npmJs === null ? [] : [npmJs];
+    install = { running: true, actionId: action.id, startedAt: Date.now(), finishedAt: 0, output: '', code: null, error: '' };
+    const args = action.id === 'install-cli-global'
+        ? [...npmArgs, 'install', '-g', SLIDEV_INSTALL_SPEC]
+        : [...npmArgs, 'install'];
+    let r;
+    try {
+        r = await runCommand(npmCmd, args, {
+            ...(action.cwd === '' ? {} : { cwd: action.cwd }),
+            timeoutMs: INSTALL_TIMEOUT_MS,
+        });
+    }
+    finally {
+        install = { ...install, running: false, finishedAt: Date.now() };
+    }
+    const output = r.out.slice(-MAX_INSTALL_OUTPUT);
+    const failed = r.error !== undefined || r.code !== 0;
+    install = {
+        running: false,
+        actionId: action.id,
+        startedAt: install.startedAt,
+        finishedAt: Date.now(),
+        output,
+        code: r.code,
+        error: r.error ?? (failed ? `安装进程退出码 ${String(r.code)}` : ''),
+    };
+    // 安装可能带来新 CLI / 新依赖：清缓存并复检（复检结果一并回给客户端）。
+    resetSlidevBinCache();
+    resetSlidevEnvCache();
+    const after = await checkSlidevEnv({ slidesAbs: opts.slidesAbs });
+    const result = {
+        ok: !failed,
+        actionId: action.id,
+        command: `${action.command}${action.cwd === '' ? '' : `（在 ${action.cwd}）`}`,
+        code: r.code,
+        output,
+        error: r.error ?? (failed ? `安装进程退出码 ${String(r.code)}` : ''),
+        report: after,
+    };
+    return { ok: true, result };
+}
+// ---------------------------------------------------------------------------
+// HTTP 处理：GET /aero-kb/slidev/env?p=<rel>&cwd=…&force=1
+//            POST /aero-kb/slidev/env  {actionId, token, confirm, p, cwd}
+// ---------------------------------------------------------------------------
+function sendJson(res, code, body) {
+    res.statusCode = code;
+    res.setHeader('Content-Type', 'application/json; charset=utf-8');
+    res.setHeader('Cache-Control', 'no-store');
+    res.end(JSON.stringify(body));
+}
+async function readJsonBody(req, limit = 64 * 1024) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buf = chunk;
+        size += buf.length;
+        if (size > limit)
+            throw new Error('请求体过大');
+        chunks.push(buf);
+    }
+    if (size === 0)
+        return {};
+    const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        throw new Error('请求体必须是 JSON 对象');
+    return parsed;
+}
+/** 只接受本页发起的请求（同源校验，防止其它站点借道触发安装）。 */
+function sameOrigin(req) {
+    const origin = req.headers.origin;
+    if (typeof origin !== 'string' || origin === '')
+        return true; // 同源 fetch / 非浏览器客户端不带 Origin
+    const host = req.headers.host;
+    if (typeof host !== 'string' || host === '')
+        return false;
+    try {
+        const u = new URL(origin);
+        return u.host === host && (u.protocol === 'http:' || u.protocol === 'https:');
+    }
+    catch {
+        return false;
+    }
+}
+/** slides.md 相对路径 → 绝对路径（限 KB 根内）。 */ function slidesAbsOf(root, rel) {
+    if (rel === '')
+        return undefined;
+    const abs = path.resolve(root, rel);
+    const prefix = root.endsWith(path.sep) ? root : root + path.sep;
+    if (abs !== root && !abs.startsWith(prefix))
+        return undefined;
+    return path.basename(abs).toLowerCase() === 'slides.md' ? abs : undefined;
+}
+/**
+ * /aero-kb/slidev/env 路由：
+ *   GET  → 体检报告（?p=<slides.md 相对路径> 时附带该课件的主题/依赖检查；?force=1 强制复检）
+ *   POST → 执行修复动作（必须带体检返回的 token 且 confirm=true）
+ */
+export async function handleSlidevEnv(req, res, opts) {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const hintCwd = url.searchParams.get('cwd') ?? undefined;
+    const root = opts.resolveKbRoot(hintCwd);
+    try {
+        if (req.method === 'POST') {
+            if (!sameOrigin(req)) {
+                sendJson(res, 403, { ok: false, error: '拒绝跨站请求。' });
+                return;
+            }
+            const body = await readJsonBody(req);
+            const rel = typeof body.p === 'string' ? body.p : (url.searchParams.get('p') ?? '');
+            const slidesAbs = root === null ? undefined : slidesAbsOf(root, rel);
+            const outcome = await runEnvFix({
+                actionId: typeof body.actionId === 'string' ? body.actionId : '',
+                token: typeof body.token === 'string' ? body.token : '',
+                confirm: body.confirm === true,
+                slidesAbs,
+            });
+            if (!outcome.ok) {
+                sendJson(res, outcome.code, { ok: false, error: outcome.error, install: currentInstallState() });
+                return;
+            }
+            sendJson(res, 200, { ok: true, result: outcome.result, install: currentInstallState() });
+            return;
+        }
+        if (req.method !== 'GET') {
+            res.statusCode = 405;
+            res.setHeader('Allow', 'GET, POST');
+            res.end('method not allowed');
+            return;
+        }
+        const rel = url.searchParams.get('p') ?? '';
+        const slidesAbs = root === null ? undefined : slidesAbsOf(root, rel);
+        // force=1 是用户的「重新体检」动作：必须连 CLI 解析缓存一起丢。
+        // 解析失败会在模块级永久缓存 null，只清体检缓存的话，用户装好 CLI 后点「重新体检」
+        // 仍会看到「未找到 slidev 命令」，只能重启 DSH 才能恢复。
+        if (url.searchParams.get('force') === '1')
+            resetSlidevBinCache();
+        const report = await getSlidevEnv({ slidesAbs }, url.searchParams.get('force') === '1');
+        sendJson(res, 200, { ok: true, report, install: currentInstallState() });
+    }
+    catch (e) {
+        sendJson(res, 500, { ok: false, error: e instanceof Error ? e.message : String(e) });
+    }
+}
+//# sourceMappingURL=slidevEnv.js.map