@mbws/plugin-sdk 0.2.1 → 0.2.3

package/dist/client.d.ts

@@ -16,20 +16,38 @@
 import { type FetchContractOptions, type PluginContract } from "./contract.js";
 import { type MbwsErrorCode } from "./errors.js";
 import type { MbwsErrorPayload } from "./protocol.js";
+/**
+ * 插件契约类型形状——mbws.contract.gen.ts 生成的 `MbwsContract` 满足它，
+ * `createMbws<MbwsContract>()` 据此把 data.read / data.apply 类型化；
+ * 不传泛型时退宽类型（Record<string, unknown>），与生成前的用法完全兼容。
+ */
+export interface MbwsContractTypes {
+    inputs: Record<string, unknown>;
+    outputs: Record<string, unknown>;
+}
+/** C 的 inputs 面（C 未声明时退宽 Record） */
+export type MbwsContractInputs<C> = C extends {
+    inputs: infer I;
+} ? I : Record<string, unknown>;
+/** C 的 outputs 面（C 未声明时退宽 Record） */
+export type MbwsContractOutputs<C> = C extends {
+    outputs: infer O;
+} ? O : Record<string, unknown>;
 /**
  * createMbws() 的返回形态（设计稿 §6.3 命名空间方法面）。
  * 未授予的命名空间在对象上不存在（未装/未授 → 属性 undefined）；caps.* 由能力包
  * 动态注册（M3 起），协议固定面不硬编码。
  */
-export interface MbwsClient {
-    /** 工人会话数据面：read 读 slot 值 / blob 拿签名 URL / apply 经 write gate 写回 */
+export interface MbwsClient<C extends MbwsContractTypes = MbwsContractTypes> {
+    /** 工人会话数据面：read 读 slot 值 / blob 拿签名 URL / apply 经 write gate 写回。
+     *  泛型 C 来自契约快照（mbws.contract.gen.ts）时，read/apply 的键与值类型随之收紧 */
     data?: {
-        read(key: string): Promise<unknown>;
-        blob(key: string): Promise<{
+        read<K extends string & keyof MbwsContractInputs<C>>(key: K): Promise<MbwsContractInputs<C>[K]>;
+        blob<K extends string & keyof MbwsContractInputs<C>>(key: K): Promise<{
             url: string;
             mime?: string;
         }>;
-        apply(outputs: Record<string, unknown>): Promise<void>;
+        apply(outputs: MbwsContractOutputs<C>): Promise<void>;
     };
     /** 运行时：进度上报 / 日志 / 取消信号（桥 mbws:event cancel） */
     runtime?: {
@@ -96,4 +114,4 @@ export declare function connectMbwsPort(port: MessagePort, init: {
 export declare function bootstrapFromWindow(win: Pick<Window, "parent" | "addEventListener" | "removeEventListener"> & {
     document?: Document;
 }, opts?: CreateMbwsOptions): Promise<MbwsClient>;
-export declare function createMbws(opts?: CreateMbwsOptions): Promise<MbwsClient>;
+export declare function createMbws<C extends MbwsContractTypes = MbwsContractTypes>(opts?: CreateMbwsOptions): Promise<MbwsClient<C>>;

package/dist/client.js

@@ -203,8 +203,10 @@ export async function createMbws(opts = {}) {
     }
     acquired = true;
     const win = typeof window !== "undefined" ? window : undefined;
-    // 无 window（纯 node）也走 dev mock（bootstrapFromWindow 内含顶窗口分支）
+    // 无 window（纯 node）也走 dev mock（bootstrapFromWindow 内含顶窗口分支）。
+    // 泛型只作用于编辑期（data.read/apply 的键值类型），运行时形态与 C 无关——
+    // dev mock / 端口客户端原样透传即可
     if (!win)
         return createDevMockMbws();
-    return bootstrapFromWindow(win, opts);
+    return (await bootstrapFromWindow(win, opts));
 }

package/dist/index.js

@@ -12,5 +12,8 @@ export * from "./dev-mock.js";
 export * from "./errors.js";
 export * from "./manifest.js";
 export * from "./protocol.js";
+// schema-types（契约→TS codegen）不进根入口：它依赖 json-schema-to-typescript +
+// prettier（Node 端），浏览器 bundle 拉根入口会炸（0.2.2 打包 bug）——
+// 只经 ./vite 子路径暴露（Node 工具链场景）
 export * from "./uuid.js";
 export * from "./version.js";

package/dist/schema-types.d.ts

@@ -0,0 +1,14 @@
+/** 契约拉取响应里类型生成关心的字段（snake_case 原样，见 fetchContract） */
+export interface ContractTypesInput {
+    pluginCode: string;
+    title?: string;
+    /** ISO 时间；仅写进文件头注释作契约版本参考 */
+    updatedAt?: string;
+    inputs: Record<string, unknown>;
+    outputs: Record<string, unknown>;
+}
+/**
+ * 生成 mbws.contract.gen.ts 全文（与文件现状 diff 后由调用方决定是否落盘）。
+ * compile 是 async（内部 prettier 格式化），调用方 await。
+ */
+export declare function generateContractTypes(contract: ContractTypesInput): Promise<string>;

package/dist/schema-types.js

@@ -0,0 +1,67 @@
+/**
+ * 契约 → TS 类型快照生成 —— 服务端按插件编号实时派生的 inputs/outputs JSON Schema
+ * 转成 TS 源码（mbws.contract.gen.ts），配合 createMbws<MbwsContract>() 让
+ * data.read / data.apply 在编辑期就有类型。
+ *
+ * 转换本体委托 json-schema-to-typescript（业界标准实现，allOf/$ref/enum/naming
+ * 等边角全覆盖）——本模块只负责「契约响应 → 组装成单一 schema → 加文件头」。
+ *
+ * 诚实边界：类型是拉取时刻的快照，不实时跟随服务端契约变更——真变更以运行时
+ * write-gate 校验为准，快照只提供「编辑期提前报错」的第一道。
+ */
+import { compile } from "json-schema-to-typescript";
+/** 契约键 → 合法 TS 标识符（PascalCase；非标识符字符压成下划线，数字开头补前缀） */
+function pascalName(key) {
+    const ident = key.replace(/[^\w$]/g, "_");
+    const pascal = `${ident.charAt(0).toUpperCase()}${ident.slice(1)}`;
+    return /^[A-Za-z_$]/.test(pascal) ? pascal : `_${pascal}`;
+}
+/**
+ * inputs/outputs 顶层键在生成的类型里全部必填（键集即契约面）。
+ * 每个顶层 schema 注入 PascalCase title：json-schema-to-typescript 把带
+ * additionalProperties:false 的匿名对象抽成独立声明，名字取 title——不注入
+ * 会得到 NoName/NoName1（契约自带的中文 title 不是合法标识符，同样触发）。
+ * 包一层对象不直接改原 schema（浅拷贝足够，嵌套结构原样引用）。
+ */
+function asRequiredObject(properties, side) {
+    const titled = Object.fromEntries(Object.entries(properties).map(([key, schema]) => [
+        key,
+        { ...schema, title: pascalName(key) },
+    ]));
+    return {
+        type: "object",
+        title: `MbwsContract${side}`,
+        additionalProperties: false,
+        properties: titled,
+        required: Object.keys(properties),
+    };
+}
+/**
+ * 生成 mbws.contract.gen.ts 全文（与文件现状 diff 后由调用方决定是否落盘）。
+ * compile 是 async（内部 prettier 格式化），调用方 await。
+ */
+export async function generateContractTypes(contract) {
+    const banner = `/**
+ * mbws 契约类型（自动生成，勿手改）。
+ * 插件：${contract.pluginCode}${contract.title ? `（${contract.title}）` : ""}${contract.updatedAt ? ` · 契约更新于 ${contract.updatedAt}` : ""}
+ * 生成时机：dev server 启动时按 mbws.config.ts 的 id 拉服务端契约，变更后重启 dev 即同步。
+ * 权威以服务端实时契约 + 运行时 write-gate 校验为准，本文件仅编辑期提示。
+ */`;
+    // 单一 schema 一次编译：顶层即 MbwsContract（inputs/outputs 两属性），
+    // 顶层键注入 PascalCase title 作声明名，x-* 平台扩展键被库忽略
+    const body = await compile({
+        type: "object",
+        title: "MbwsContract",
+        required: ["inputs", "outputs"],
+        additionalProperties: false,
+        properties: {
+            inputs: asRequiredObject(contract.inputs, "Inputs"),
+            outputs: asRequiredObject(contract.outputs, "Outputs"),
+        },
+    }, "MbwsContract", {
+        bannerComment: banner,
+        enableConstEnums: false,
+        style: { singleQuote: false, semi: true, trailingComma: "all" },
+    });
+    return `${body}\n`;
+}

package/dist/version.d.ts

@@ -12,4 +12,4 @@ export declare const PROTOCOL_VERSION: 1;
  * SDK 自身版本（与 package.json version 保持一致）。
  * init-ack 上报给宿主做审计，与 manifest.sdk（build 写入）交叉核对。
  */
-export declare const SDK_VERSION = "0.0.1";
+export declare const SDK_VERSION = "0.2.3";

package/dist/version.js

@@ -12,4 +12,4 @@ export const PROTOCOL_VERSION = 1;
  * SDK 自身版本（与 package.json version 保持一致）。
  * init-ack 上报给宿主做审计，与 manifest.sdk（build 写入）交叉核对。
  */
-export const SDK_VERSION = "0.0.1";
+export const SDK_VERSION = "0.2.3";

package/dist/vite.d.ts

@@ -1,8 +1,11 @@
 import type { Plugin } from "vite";
 import { type MbwsUserConfig } from "./config.js";
+export { type ContractTypesInput, generateContractTypes } from "./schema-types.js";
 export interface MbwsVitePluginOptions {
     /** mbws.config.ts 的配置（defineConfig 回传值）——静态合同与动态开发配置同住 */
     config: MbwsUserConfig;
+    /** dev 启动时拉契约生成 mbws.contract.gen.ts 类型快照（默认 true；离线/后端不可达自动跳过） */
+    generateTypes?: boolean;
 }
 /**
  * mbws vite 插件。dev 预览下契约拉取同源化：SDK fetchContract 读到注入的

package/dist/vite.js

@@ -17,6 +17,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import { buildManifest } from "./config.js";
+import { generateContractTypes } from "./schema-types.js";
+// 契约类型生成经本子路径暴露（Node 端工具链用；依赖 prettier，不进根入口）
+export { generateContractTypes } from "./schema-types.js";
 /** dev 契约拉取的专属命名空间：同源走插件中间件转发，免 CORS */
 const DEV_CONTRACT_BASE = "/__mbws__";
 /** 后端缺省地址：插件开发者缺省连线上（拉线上 spec），本地联调走 env 或 apiBaseUrl */
@@ -41,6 +44,7 @@ function readRequestBody(req) {
  */
 export function mbwsVitePlugin(opts) {
     const { config } = opts;
+    const generateTypes = opts.generateTypes ?? true;
     // 工程 root：config 钩子里记（用户显式 root 优先），closeBundle 写产物时用
     let projectRoot = process.cwd();
     // manifest 是纯派生物，构建/供给共用同一序列化姿势（尾换行对齐文件写习惯）
@@ -90,6 +94,11 @@ export function mbwsVitePlugin(opts) {
             return incremental;
         },
         configureServer(server) {
+            // 契约类型快照生成（fire-and-forget：离线/后端不可达只告警，绝不阻塞 dev）
+            if (generateTypes) {
+                // logger 缺席（单测的极简 server mock）退 console，访问本身不抛
+                void writeContractTypesFile(config, projectRoot, (msg) => server.config?.logger?.info(msg));
+            }
             server.middlewares.use((req, res, next) => {
                 const pathname = (req.url ?? "").split("?")[0];
                 if (pathname === "/manifest.json") {
@@ -115,6 +124,33 @@ export function mbwsVitePlugin(opts) {
         },
     };
 }
+/**
+ * 拉服务端契约生成 mbws.contract.gen.ts（内容有变才落盘——重启 dev 不产生无谓改动）。
+ * 契约端点公开（按插件编号实时派生），失败只在 dev 控制台提示，不影响任何构建行为。
+ */
+async function writeContractTypesFile(config, root, log) {
+    try {
+        const response = await fetch(`${resolveApiBase(config)}/api/plugin-dev-tasks/contract/by-plugin/${encodeURIComponent(config.id)}`);
+        if (!response.ok)
+            throw new Error(`HTTP ${response.status}`);
+        const data = (await response.json());
+        const source = await generateContractTypes({
+            pluginCode: config.id,
+            title: typeof data.title === "string" ? data.title : undefined,
+            updatedAt: typeof data.updated_at === "string" ? data.updated_at : undefined,
+            inputs: data.inputs ?? {},
+            outputs: data.outputs ?? {},
+        });
+        const file = path.resolve(root, "mbws.contract.gen.ts");
+        if (!fs.existsSync(file) || fs.readFileSync(file, "utf8") !== source) {
+            fs.writeFileSync(file, source);
+            log("[mbws] 契约类型已生成/更新：mbws.contract.gen.ts（createMbws<MbwsContract>() 即获类型）");
+        }
+    }
+    catch (error) {
+        log(`[mbws] 契约类型生成跳过：${error instanceof Error ? error.message : error}（不影响 dev）`);
+    }
+}
 /** /__mbws__/<rest> → <apiBase>/<rest>：方法/头透传，响应状态码/content-type/body 透传 */
 async function forwardApi(config, req, res) {
     const pathname = (req.url ?? "").split("?")[0];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mbws/plugin-sdk",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Moye 插件开发 SDK——panel/viewer 与宿主的类型定义与运行时端口适配",
   "license": "MIT",
   "type": "module",
@@ -23,6 +23,7 @@
     "dist"
   ],
   "dependencies": {
+    "json-schema-to-typescript": "^16.0.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {