@skillbuilder/miniapp-simulator 0.0.0-stage → 0.2.0

package/lib/types/worker/adapters/package-policy.d.ts

@@ -0,0 +1,12 @@
+import type { WorkerCspPolicy } from "./csp-policy";
+import type { WorkerGuardConfig } from "./protocol";
+export interface MiniAppWorkerOptions {
+    /** 仅 loadZip/loadFiles 的包内 classic Worker 可启用，默认 false。 */
+    enabled?: boolean;
+}
+/** 随 MOUNT 发送给资源 Service Worker 的会话策略。 */
+export interface WorkerMountPolicy {
+    sessionId: string;
+    csp?: WorkerCspPolicy;
+}
+export declare function createPackageWorkerConfig(options: MiniAppWorkerOptions | undefined, sessionId: string): WorkerGuardConfig | undefined;

package/lib/types/worker/adapters/page-lifecycle.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/worker/adapters/protocol.d.ts

@@ -0,0 +1,49 @@
+/** 宿主在业务代码前提供本次页面会话的 Worker 配置。 */
+export interface WorkerGuardConfig {
+    protocolVersion: number;
+    sessionId: string;
+    enabled: boolean;
+    /** 宿主初始可见性；默认 visible，与 document.hidden 共同判断。 */
+    initialState?: "visible" | "hidden";
+}
+export interface WorkerRuntimeMetadata {
+    readonly name: string;
+    readonly version: string;
+    readonly protocolVersion: number;
+    readonly workerCsp: string;
+}
+/** 模拟器维护的安全脚本接入协议；与资源 Service Worker 协议独立。 */
+export declare const WORKER_RUNTIME_METADATA: WorkerRuntimeMetadata;
+export declare const WORKER_RUNTIME_PROTOCOL_VERSION: number;
+export declare const WORKER_CONTENT_SECURITY_POLICY: string;
+export declare const WORKER_BACKGROUND_TIMEOUT_MS = 30000;
+export type WorkerTerminateFlag = "主动" | "system";
+export type WorkerTerminateCallback = (flag: WorkerTerminateFlag) => void;
+export interface WorkerRuntimeState {
+    readonly protocolVersion: number;
+    readonly sessionId: string;
+    readonly enabled: boolean;
+    readonly maxWorkers: number;
+    readonly state: "visible" | "hidden" | "destroyed";
+    readonly recycled: boolean;
+}
+export interface WorkerGuardController {
+    readonly supported: boolean;
+    readonly context: WorkerRuntimeState;
+    updateVisibility(visible: boolean): void;
+    reclaim(): void;
+    destroy(): void;
+}
+declare global {
+    interface Worker {
+        /** 平台终止通知；浏览器/系统直接结束进程及 self.close 不保证可观测。 */
+        onTerminate(callback: WorkerTerminateCallback): void;
+        offTerminate(callback?: WorkerTerminateCallback): void;
+    }
+    interface Window {
+        /** 宿主在安全脚本前注入的 Worker 配置，只读、同一页面会话固定。 */
+        readonly __MINITOOL_WORKER_CONTEXT__?: Readonly<WorkerGuardConfig>;
+        /** 运行时输出；业务只读，不能作为控制入口。 */
+        readonly __MINITOOL_WORKER_STATE__: WorkerRuntimeState;
+    }
+}

package/lib/types/worker/adapters/scripts.d.ts

@@ -0,0 +1,2 @@
+/** 在私有闭包中连接安全脚本返回的 Worker 控制器与模拟器宿主消息通道。 */
+export declare function buildWorkerLifecycleScript(sealSource: string): string;

package/lib/types/worker/adapters/service-worker.d.ts

@@ -0,0 +1,2 @@
+/** 为当前包页面的 Worker 请求返回原始文件与 CSP，保持实例间资源隔离。 */
+export declare function serveWorkerRequest(request: Request, clientId: string): Promise<Response>;

package/lib/workbench-server.mjs

@@ -0,0 +1,183 @@
+import { once as I } from "node:events";
+import u from "node:fs/promises";
+import { createRequire as A } from "node:module";
+import n from "node:path";
+import { format as U } from "node:url";
+import j from "@koa/router";
+import { send as S } from "@koa/send";
+import F from "koa";
+import { PassThrough as _ } from "node:stream";
+import { watch as L } from "chokidar";
+const O = "https://miniapp-sandbox.xiaohongshu.com/simulator/";
+var b = /* @__PURE__ */ ((e) => (e.skillDesignable = "skill-designable", e.creator = "creator", e.mars = "mars", e.dev = "dev", e))(b || {});
+function C(e, t) {
+  const s = e.filter(
+    (r) => !r.includes("/") && n.extname(r).toLowerCase() === ".html"
+  );
+  if (s.includes("index.html")) return "index.html";
+  if (s.length === 1) return s[0];
+  throw new Error(
+    s.length === 0 ? `调试根目录中没有 HTML 文件：${t}` : `调试根目录中有多个 HTML 文件，请将入口命名为 index.html：${t}`
+  );
+}
+async function g(e) {
+  const t = [];
+  async function s(r) {
+    for (const i of await u.readdir(r, { withFileTypes: !0 })) {
+      if (i.name.startsWith(".")) continue;
+      const l = n.join(r, i.name);
+      i.isDirectory() ? await s(l) : i.isFile() && t.push(n.relative(e, l).split(n.sep).join("/"));
+    }
+  }
+  return await s(e), { entry: C(t, e), files: t };
+}
+async function N(e) {
+  const t = n.resolve(e);
+  if (!(await u.stat(t).catch(() => null))?.isDirectory()) throw new Error(`调试根目录不存在：${t}`);
+  return u.realpath(t);
+}
+async function D(e, t) {
+  const s = await u.realpath(n.resolve(e, t)), r = n.relative(e, s);
+  if (r === ".." || r.startsWith(`..${n.sep}`) || n.isAbsolute(r))
+    throw Object.assign(new Error("Forbidden"), { status: 403 });
+  return s;
+}
+const E = `event: reload
+data: {}
+
+`, H = /\.(?:html|[cm]?js|css)$/i;
+async function M(e) {
+  const t = /* @__PURE__ */ new Set();
+  let s, r = !1;
+  const i = (a) => {
+    for (const h of t) h.write(a);
+  }, l = L(e, {
+    ignoreInitial: !0,
+    followSymlinks: !1,
+    atomic: !0,
+    awaitWriteFinish: { stabilityThreshold: 150, pollInterval: 50 },
+    ignored: (a, h) => h?.isSymbolicLink() || n.relative(e, a).split(n.sep).some((f) => f.startsWith(".") || f === "node_modules")
+  });
+  l.on("all", (a, h) => {
+    r || !["add", "change", "unlink"].includes(a) || !H.test(h) || (clearTimeout(s), s = setTimeout(() => i(E), 200));
+  }), l.on("error", () => {
+    i(`event: watch-error
+data: 本地文件监听异常，请检查目录或重启本地服务。
+
+`);
+  });
+  try {
+    await I(l, "ready");
+  } catch (a) {
+    throw r = !0, clearTimeout(s), await l.close(), a;
+  }
+  const d = setInterval(() => i(`: heartbeat
+
+`), 15e3);
+  return d.unref(), {
+    subscribe() {
+      if (r) throw Object.assign(new Error("Service unavailable"), { status: 503 });
+      const a = new _();
+      return t.add(a), a.once("close", () => t.delete(a)), a.write(`retry: 1000
+${E}`), a;
+    },
+    async close() {
+      r = !0, clearTimeout(s), clearInterval(d);
+      for (const a of t) a.end();
+      t.clear(), await l.close();
+    }
+  };
+}
+const k = "127.0.0.1", c = "/__miniapp_workbench__", P = async (e, t) => {
+  if (e.set({ "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" }), e.method !== "GET" && e.method !== "HEAD") {
+    e.set("Allow", "GET, HEAD"), e.status = 405, e.body = "Method Not Allowed";
+    return;
+  }
+  try {
+    decodeURI(e.path), await t();
+  } catch (s) {
+    const r = s, i = ["ENOENT", "ENOTDIR", "EISDIR"].includes(r.code ?? "");
+    e.status = r.status ?? (i ? 404 : 500), s instanceof URIError && (e.status = 400), e.type = "text", e.body = "Resource unavailable";
+  }
+};
+async function R(e, t, s) {
+  const r = await D(t, s), i = n.relative(t, r);
+  e.assert(i, 404), await S(e, encodeURIComponent(i), {
+    root: t,
+    gzip: !1,
+    brotli: !1
+  });
+}
+async function Z(e) {
+  const t = new URL(e.remote?.serviceUrl ?? O);
+  if (!["http:", "https:"].includes(t.protocol))
+    throw new Error("remote.serviceUrl 仅支持 http / https URL");
+  const s = e.remote?.businessLine ?? b.skillDesignable;
+  if (!Object.values(b).includes(s))
+    throw new Error(`不支持的 businessLine：${s}`);
+  const r = await N(e.rootDir);
+  await g(r);
+  const i = A(import.meta.url).resolve(
+    "@skillbuilder/miniapp-simulator/workbench.html"
+  ), l = n.resolve(n.dirname(i), "../.."), d = await u.realpath(n.join(l, "lib"));
+  try {
+    await u.access(n.join(d, "workbench.js"));
+  } catch {
+    throw new Error("工作台 SDK 产物缺失，请先执行 build:npm");
+  }
+  const a = {
+    schemaVersion: 2,
+    projectName: n.basename(n.basename(r) === "dist" ? n.dirname(r) : r),
+    viewport: { width: 393, height: 852 },
+    sdkUrl: `${c}/sdk/workbench.js`,
+    remote: {
+      serviceUrl: t.href,
+      appId: e.remote?.appId?.trim() || "local-workbench",
+      businessLine: s,
+      tracker: !1
+    },
+    artifact: {
+      type: "files",
+      url: `${c}/manifest.json`,
+      baseUrl: `${c}/files/`,
+      eventsUrl: `${c}/events`
+    }
+  }, h = await u.readFile(i), f = await M(r), p = new F();
+  p.silent = !0;
+  const m = new j();
+  p.use(P), m.get(["/", "/index.html"], (o) => {
+    o.type = "html", o.body = h;
+  }), m.get(`${c}/config.json`, (o) => {
+    o.body = a;
+  }), m.get(`${c}/manifest.json`, async (o) => {
+    o.body = await g(r);
+  }), m.get(`${c}/files/*file`, (o) => R(o, r, o.params.file)), m.get(`${c}/sdk/*file`, (o) => R(o, d, o.params.file)), m.get(`${c}/events`, (o) => {
+    o.type = "text/event-stream", o.set({ Connection: "keep-alive", "X-Accel-Buffering": "no" }), o.status = 200, o.method !== "HEAD" && (o.body = f.subscribe());
+  }), m.get("/favicon.ico", (o) => {
+    o.status = 204;
+  }), p.use(m.routes());
+  const w = p.listen(0, k);
+  try {
+    await I(w, "listening");
+  } catch (o) {
+    throw await f.close(), o;
+  }
+  const T = w.address();
+  let v;
+  return {
+    url: U({ protocol: "http:", hostname: k, port: T.port, pathname: "/" }),
+    close() {
+      return v ??= Promise.all([
+        f.close(),
+        new Promise((o, $) => {
+          w.close((y) => y ? $(y) : o());
+        })
+      ]).then(() => {
+      }), v;
+    }
+  };
+}
+export {
+  b as BusinessLine,
+  Z as startWorkbenchServer
+};