@mbws/plugin-sdk 0.2.3 → 0.3.0

package/dist/vite.js

@@ -14,9 +14,11 @@
  *
  * vite 只进 devDependencies 供类型与测试（type-only import），SDK 产物不依赖 vite。
  */
+import { spawn, spawnSync } from "node:child_process";
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { buildManifest } from "./config.js";
+import { buildManifest, resolveAttachmentRefs } from "./config.js";
 import { generateContractTypes } from "./schema-types.js";
 // 契约类型生成经本子路径暴露（Node 端工具链用；依赖 prettier，不进根入口）
 export { generateContractTypes } from "./schema-types.js";
@@ -47,8 +49,31 @@ export function mbwsVitePlugin(opts) {
     const generateTypes = opts.generateTypes ?? true;
     // 工程 root：config 钩子里记（用户显式 root 优先），closeBundle 写产物时用
     let projectRoot = process.cwd();
-    // manifest 是纯派生物，构建/供给共用同一序列化姿势（尾换行对齐文件写习惯）
-    const manifestJson = () => `${JSON.stringify(buildManifest(config), null, 2)}\n`;
+    // 附件声明的解析缓存（dev 会话内；build 每次新鲜解析防用陈旧 hash 出产物）
+    let resolvedAttachmentsCache = null;
+    const ensureAttachments = async () => {
+        const refs = config.attachments ?? [];
+        if (refs.length === 0)
+            return [];
+        if (resolvedAttachmentsCache)
+            return resolvedAttachmentsCache;
+        resolvedAttachmentsCache = await resolveAttachmentRefs(refs, resolveApiBase(config));
+        return resolvedAttachmentsCache;
+    };
+    // manifest 是纯派生物，构建/供给共用同一序列化姿势（尾换行对齐文件写习惯）。
+    // dev 附件解析失败时降级空附件出 manifest（dev-mock 不依赖它），build 不允许
+    const manifestJson = async (dev) => {
+        try {
+            const decls = await ensureAttachments();
+            return `${JSON.stringify(buildManifest(config, { resolvedAttachments: decls }), null, 2)}\n`;
+        }
+        catch (error) {
+            if (dev) {
+                return `${JSON.stringify(buildManifest(config, { allowEmptyAttachments: true }), null, 2)}\n`;
+            }
+            throw error;
+        }
+    };
     // 解包形态目录 <id>@<version>/：静态产物与 manifest 同目录（CI 的 tar -C 按它整目录打包）
     const distDir = () => path.resolve(projectRoot, `dist/${config.id}@${config.version}`);
     return {
@@ -76,7 +101,10 @@ export function mbwsVitePlugin(opts) {
                 buildDefaults.outDir = distDir();
             if (!userConfig.build?.rollupOptions?.input) {
                 buildDefaults.rollupOptions = {
-                    input: [path.resolve(projectRoot, "panel.html"), path.resolve(projectRoot, "viewer.html")],
+                    input: [
+                        path.resolve(projectRoot, "panel.html"),
+                        path.resolve(projectRoot, "viewer.html"),
+                    ],
                 };
             }
             if (Object.keys(buildDefaults).length > 0)
@@ -104,8 +132,38 @@ export function mbwsVitePlugin(opts) {
                 if (pathname === "/manifest.json") {
                     // dev 虚拟供给：SDK fetchContract 的 manifest 兜底读取在 dev/产物两形态行为一致
                     res.setHeader("content-type", "application/json");
-                    res.end(manifestJson());
-                    return;
+                    return manifestJson(true)
+                        .then((body) => {
+                        res.end(body);
+                    })
+                        .catch(next);
+                }
+                if (pathname === "/__mbws__/dev/exec") {
+                    if (req.method !== "POST") {
+                        res.statusCode = 405;
+                        res.end();
+                        return;
+                    }
+                    // dev 真执行：Node 侧 spawn 附件（本地覆盖优先，否则按声明自动下载官方附件库）
+                    return handleDevExec(config, projectRoot, req, res).catch(next);
+                }
+                if (pathname === "/__mbws__/dev/localize") {
+                    const ref = new URL(req.url ?? "/", "http://dev").searchParams.get("ref") ?? "";
+                    if (!ref) {
+                        res.statusCode = 400;
+                        res.end();
+                        return;
+                    }
+                    return handleDevLocalize(projectRoot, res, ref).catch(next);
+                }
+                if (pathname === "/__mbws__/dev/file") {
+                    const relPath = new URL(req.url ?? "/", "http://dev").searchParams.get("path") ?? "";
+                    if (!relPath) {
+                        res.statusCode = 400;
+                        res.end();
+                        return;
+                    }
+                    return handleDevFile(projectRoot, req, res, relPath).catch(next);
                 }
                 if (pathname.startsWith(`${DEV_CONTRACT_BASE}/api`)) {
                     // 转发异步进行，失败交 next（connect 约定）；返回 promise 供测试 await
@@ -115,12 +173,15 @@ export function mbwsVitePlugin(opts) {
                 return undefined;
             });
         },
-        closeBundle() {
-            // 产物直出解包形态目录 <id>@<version>/，桌面 MBWS_DEV_PLUGIN_DIR 指向 dist 即装载
+        async closeBundle() {
+            // 产物直出解包形态目录 <id>@<version>/，桌面 MBWS_DEV_PLUGIN_DIR 指向 dist 即装载。
+            // 附件声明新鲜解析（不缓存）：产物钉官方库当前 hash，解析失败炸构建是正确行为
             const outDir = distDir();
             // mkdir 容错：在线构建场景 outDir 被平台覆盖，本目录可能不存在（写失败会炸构建）
             fs.mkdirSync(outDir, { recursive: true });
-            fs.writeFileSync(path.join(outDir, "manifest.json"), manifestJson());
+            const refs = config.attachments ?? [];
+            const decls = refs.length > 0 ? await resolveAttachmentRefs(refs, resolveApiBase(config)) : [];
+            fs.writeFileSync(path.join(outDir, "manifest.json"), `${JSON.stringify(buildManifest(config, { resolvedAttachments: decls }), null, 2)}\n`);
         },
     };
 }
@@ -152,6 +213,308 @@ async function writeContractTypesFile(config, root, log) {
     }
 }
 /** /__mbws__/<rest> → <apiBase>/<rest>：方法/头透传，响应状态码/content-type/body 透传 */
+// —— 以下为 dev 执行中间件（serve 专属）：真 spawn 附件二进制，NDJSON 流回事件 ——
+/**
+ * 当前进程 → 附件平台键（与 manifest 的 ATTACHMENT_PLATFORMS 同词表）。
+ */
+export function currentAttachmentPlatform() {
+    const os = process.platform === "win32" ? "win" : process.platform === "darwin" ? "darwin" : "linux";
+    return `${os}-${process.arch === "arm64" ? "arm64" : "x64"}`;
+}
+/** dev 附件缓存目录（工程内，应进插件工程 .gitignore） */
+const DEV_ATTACHMENT_CACHE = ".mbws/attachments";
+/**
+ * dev 用附件本地覆盖：env MBWS_DEV_ATTACHMENT_<NAME>（名字大写、- → _）优先，
+ * 其次 attachments 声明里的 devPath（线上还没有的新版本指本机路径）。
+ * 未配置/路径不存在返回 null（走官方附件库自动下载）。
+ */
+export function resolveDevAttachmentOverride(config, name) {
+    const envValue = process.env[`MBWS_DEV_ATTACHMENT_${name.replace(/-/g, "_").toUpperCase()}`];
+    if (envValue && fs.existsSync(envValue))
+        return envValue;
+    const ref = (config.attachments ?? []).find((a) => a.name === name);
+    if (typeof ref?.devPath === "string" && fs.existsSync(ref.devPath))
+        return ref.devPath;
+    return null;
+}
+/** 同一附件并发解析去重（下载进行中第二个 spawn 等同一 Promise） */
+const inflightDevAttachments = new Map();
+/**
+ * resolve 端点结果的 dev 会话级 memo（name@version → 下载参数）。版本即 hash 锚，
+ * 同版本重复 spawn 不再查端点；重发附件（应换版本）后重启 dev 即同步。
+ */
+const devAttachmentResolves = new Map();
+/**
+ * 确保官方附件库附件在本地就绪：按 config.attachments 声明查 resolve 端点，
+ * 内容寻址缓存 `.mbws/attachments/<name>@<version>/<sha256>/<entry>`——命中零下载；
+ * 未命中流式下载（sha256 校验）+ `tar -xf` 解包（bsdtar 通吃 tar.gz/zip）+ chmod 755。
+ * 附件未声明 / 库未登记返回 null（调用方回 501）；下载/校验/解包失败抛错。
+ * log 收下载进度行（调用方转 NDJSON 事件流）。
+ */
+async function ensureLibraryAttachment(config, root, name, log) {
+    const key = `${root}::${name}`;
+    const inflight = inflightDevAttachments.get(key);
+    if (inflight)
+        return inflight;
+    const task = (async () => {
+        const ref = (config.attachments ?? []).find((a) => a.name === name);
+        if (!ref)
+            return null;
+        const platform = currentAttachmentPlatform();
+        const resolveKey = `${name}@${ref.version}`;
+        let resolved = devAttachmentResolves.get(resolveKey);
+        if (!resolved) {
+            try {
+                const response = await fetch(`${resolveApiBase(config)}/api/plugin-attachments/resolve` +
+                    `?name=${encodeURIComponent(name)}&version=${encodeURIComponent(ref.version)}` +
+                    `&platform=${platform}`);
+                // 未登记/平台缺失/后端不可达都归「dev 不可用」，交给调用方 501 文案
+                if (!response.ok)
+                    return null;
+                resolved = (await response.json());
+                devAttachmentResolves.set(resolveKey, resolved);
+            }
+            catch {
+                return null;
+            }
+        }
+        // win 平台包内入口带 .exe 后缀（publish 脚本布局），显式 entry 原样用
+        const entry = ref.entry ?? `${name}${platform.startsWith("win") ? ".exe" : ""}`;
+        const dir = path.join(root, DEV_ATTACHMENT_CACHE, `${name}@${ref.version}`, resolved.sha256);
+        const entryPath = path.join(dir, entry);
+        if (fs.existsSync(entryPath))
+            return entryPath;
+        log(`[mbws:dev] 下载附件 ${name}@${ref.version}（${platform}，${Math.round(resolved.size / 1e6)} MB）`);
+        fs.mkdirSync(dir, { recursive: true });
+        const tmpPath = path.join(dir, `download.${resolved.archive}`);
+        try {
+            const response = await fetch(resolved.url);
+            if (!response.ok || !response.body)
+                throw new Error(`下载 HTTP ${response.status}`);
+            const hash = crypto.createHash("sha256");
+            const out = fs.createWriteStream(tmpPath);
+            let received = 0;
+            let lastReported = 0;
+            // Node fetch 的 body 是 async iterable：流式落盘 + 边下边算 hash（不整包进内存）
+            for await (const chunk of response.body) {
+                const bytes = Buffer.from(chunk);
+                hash.update(bytes);
+                out.write(bytes);
+                received += bytes.byteLength;
+                if (received - lastReported >= 5 * 1e6) {
+                    lastReported = received;
+                    log(`[mbws:dev] 下载中 ${Math.round(received / 1e6)} / ${Math.round(resolved.size / 1e6)} MB`);
+                }
+            }
+            await new Promise((resolve, reject) => out.end((error) => (error ? reject(error) : resolve())));
+            const sha256 = hash.digest("hex");
+            if (sha256 !== resolved.sha256) {
+                throw new Error(`sha256 不符（期望 ${resolved.sha256}，实得 ${sha256}）`);
+            }
+            const extracted = spawnSync("tar", ["-xf", tmpPath, "-C", dir]);
+            if (extracted.status !== 0) {
+                throw new Error(`解包失败：${extracted.stderr?.toString().trim() || `tar exit ${extracted.status}`}`);
+            }
+            if (!fs.existsSync(entryPath))
+                throw new Error(`解包后未见入口 ${entry}`);
+            fs.chmodSync(entryPath, 0o755);
+            log(`[mbws:dev] 附件 ${name}@${ref.version} 就绪（已缓存，后续零下载）`);
+            return entryPath;
+        }
+        finally {
+            fs.rmSync(tmpPath, { force: true });
+        }
+    })();
+    inflightDevAttachments.set(key, task);
+    try {
+        return await task;
+    }
+    finally {
+        inflightDevAttachments.delete(key);
+    }
+}
+/** POST /__mbws__/dev/exec：spawn 本机二进制（cwd = 工程根，插件 args 里 samples/xxx 相对可用） */
+async function handleDevExec(config, root, req, res) {
+    let body;
+    try {
+        body = JSON.parse((await readRequestBody(req)).toString("utf8"));
+    }
+    catch {
+        res.statusCode = 400;
+        res.end(JSON.stringify({ message: "body 不是合法 JSON" }));
+        return;
+    }
+    const { attachment, args } = body;
+    if (typeof attachment !== "string" ||
+        !Array.isArray(args) ||
+        !args.every((a) => typeof a === "string")) {
+        res.statusCode = 400;
+        res.end(JSON.stringify({ message: "attachment(string) 与 args(string[]) 必填" }));
+        return;
+    }
+    res.setHeader("content-type", "application/x-ndjson");
+    res.setHeader("cache-control", "no-store");
+    const write = (event) => res.write(`${JSON.stringify(event)}\n`);
+    // 附件解析：本地覆盖（env / devPath）零网络；未覆盖按 attachments 声明
+    // 自动从官方附件库下载缓存（下载进度经 NDJSON 事件流回面板）
+    let binPath = resolveDevAttachmentOverride(config, attachment);
+    if (!binPath) {
+        try {
+            binPath = await ensureLibraryAttachment(config, root, attachment, (text) => write({ kind: "lines", lines: [{ stream: "stderr", text }] }));
+        }
+        catch (error) {
+            // 下载/校验/解包失败：已经开始流式响应（可能已写过进度行），按 job 失败收尾
+            const message = error instanceof Error ? error.message : String(error);
+            write({ kind: "exit", exitCode: -1, stderrTail: `附件 ${attachment} 下载失败：${message}` });
+            res.end();
+            return;
+        }
+        if (!binPath) {
+            // 501 = 能力明确不可用：SDK dev-mock 收到非 2xx 退模拟执行
+            const declared = (config.attachments ?? []).some((a) => a.name === attachment);
+            res.statusCode = 501;
+            res.end(JSON.stringify({
+                message: declared
+                    ? `附件 ${attachment} 未在官方附件库登记当前平台产物（发布见 scripts/publish-attachment.mjs），或后端不可达；本机覆盖可配 attachments 的 devPath / env MBWS_DEV_ATTACHMENT_${attachment.replace(/-/g, "_").toUpperCase()}`
+                    : `mbws.config.ts 的 attachments 未声明附件 ${attachment}（dev 自动下载依赖声明）；本机覆盖可配该项 devPath / env MBWS_DEV_ATTACHMENT_${attachment.replace(/-/g, "_").toUpperCase()}`,
+            }));
+            return;
+        }
+    }
+    const proc = spawn(binPath, args, { cwd: root });
+    const stderrTailChunks = [];
+    let stderrTailBytes = 0;
+    const pendingLines = [];
+    let flushTimer = null;
+    const flush = () => {
+        if (pendingLines.length > 0)
+            write({ kind: "lines", lines: pendingLines.splice(0) });
+    };
+    const pushLine = (stream, text) => {
+        pendingLines.push({ stream, text });
+        if (!flushTimer)
+            flushTimer = setTimeout(() => {
+                flushTimer = null;
+                flush();
+            }, 100);
+    };
+    const wireLines = (source, stream) => {
+        let buffer = "";
+        source.setEncoding?.("utf8");
+        source.on("data", (chunk) => {
+            buffer += chunk;
+            let newlineAt = buffer.indexOf("\n");
+            while (newlineAt >= 0) {
+                const line = buffer.slice(0, newlineAt).replace(/\r$/, "");
+                buffer = buffer.slice(newlineAt + 1);
+                if (line)
+                    pushLine(stream, line);
+                if (stream === "stderr") {
+                    stderrTailChunks.push(Buffer.from(`${line}\n`));
+                    stderrTailBytes += line.length + 1;
+                    while (stderrTailBytes > 8192) {
+                        stderrTailBytes -= stderrTailChunks[0].length;
+                        stderrTailChunks.shift();
+                    }
+                }
+                newlineAt = buffer.indexOf("\n");
+            }
+        });
+    };
+    const timeoutMs = typeof body.timeoutMs === "number" && body.timeoutMs > 0 ? body.timeoutMs : 30 * 60_000;
+    const timer = setTimeout(() => proc.kill("SIGKILL"), timeoutMs);
+    const finish = (exitCode, stderrTail) => {
+        clearTimeout(timer);
+        if (flushTimer)
+            clearTimeout(flushTimer);
+        flush();
+        write({ kind: "exit", exitCode, stderrTail });
+        res.end();
+    };
+    if (proc.stdout)
+        wireLines(proc.stdout, "stdout");
+    if (proc.stderr)
+        wireLines(proc.stderr, "stderr");
+    proc.on("error", (error) => finish(-1, `spawn ${binPath} 失败：${error.message}`));
+    proc.on("exit", (code) => finish(code ?? -1, Buffer.concat(stderrTailChunks).toString("utf8")));
+}
+/** GET /__mbws__/dev/localize?ref=：映射到工程内 samples/ 夹具（存在才 200） */
+async function handleDevLocalize(root, res, ref) {
+    const basename = ref.split("/").pop() ?? "";
+    const filePath = path.resolve(root, "samples", basename);
+    try {
+        const stat = await fs.promises.stat(filePath);
+        if (stat.isFile()) {
+            res.setHeader("content-type", "application/json");
+            res.end(JSON.stringify({ path: `samples/${basename}`, size: stat.size }));
+            return;
+        }
+    }
+    catch {
+        // 不存在走 404
+    }
+    res.statusCode = 404;
+    res.end(JSON.stringify({ message: `samples/${basename} 不存在` }));
+}
+const DEV_FILE_MIME = {
+    ".mp4": "video/mp4",
+    ".webm": "video/webm",
+    ".mov": "video/quicktime",
+    ".m4v": "video/mp4",
+    ".mp3": "audio/mpeg",
+    ".wav": "audio/wav",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".json": "application/json",
+    ".txt": "text/plain; charset=utf-8",
+    ".vtt": "text/vtt",
+    ".srt": "text/plain; charset=utf-8",
+};
+/** GET /__mbws__/dev/file?path=：dev 媒体预览（工程内路径白名单 + Range 支持） */
+async function handleDevFile(root, req, res, relPath) {
+    const filePath = path.resolve(root, relPath);
+    if (!filePath.startsWith(path.resolve(root))) {
+        res.statusCode = 403;
+        res.end();
+        return;
+    }
+    let stat;
+    try {
+        stat = await fs.promises.stat(filePath);
+        if (!stat.isFile())
+            throw new Error("not file");
+    }
+    catch {
+        res.statusCode = 404;
+        res.end();
+        return;
+    }
+    const mime = DEV_FILE_MIME[path.extname(filePath).toLowerCase()] ?? "application/octet-stream";
+    res.setHeader("content-type", mime);
+    res.setHeader("accept-ranges", "bytes");
+    const range = req.headers.range;
+    const match = typeof range === "string" ? range.match(/^bytes=(\d*)-(\d*)$/) : null;
+    if (match) {
+        const start = match[1] ? Number(match[1]) : 0;
+        const end = match[2] ? Math.min(Number(match[2]), stat.size - 1) : stat.size - 1;
+        if (Number.isNaN(start) || start > end) {
+            res.statusCode = 416;
+            res.setHeader("content-range", `bytes */${stat.size}`);
+            res.end();
+            return;
+        }
+        res.statusCode = 206;
+        res.setHeader("content-range", `bytes ${start}-${end}/${stat.size}`);
+        res.setHeader("content-length", String(end - start + 1));
+        fs.createReadStream(filePath, { start, end }).pipe(res);
+        return;
+    }
+    res.setHeader("content-length", String(stat.size));
+    fs.createReadStream(filePath).pipe(res);
+}
 async function forwardApi(config, req, res) {
     const pathname = (req.url ?? "").split("?")[0];
     const rest = pathname.slice(DEV_CONTRACT_BASE.length);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mbws/plugin-sdk",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Moye 插件开发 SDK——panel/viewer 与宿主的类型定义与运行时端口适配",
   "license": "MIT",
   "type": "module",
@@ -11,6 +11,7 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./package.json": "./package.json",
     "./vite": {
       "types": "./dist/vite.d.ts",
       "default": "./dist/vite.js"