@capybara-hq/testing 0.0.0-stage → 0.1.0-rc.0

package/dist/fake-marketplace.d.ts

@@ -0,0 +1,25 @@
+/** One request the fake marketplace received. */
+export interface FakeMarketplaceRequest {
+    /** The `If-None-Match` header. */
+    etag?: string;
+    /** The `Authorization` header. */
+    authorization?: string;
+}
+export interface FakeMarketplace {
+    /** The manifest URL `http://127.0.0.1:<port>/marketplace.json`. */
+    url: string;
+    /** Serves another manifest (a string is served as is, for invalid JSON); the ETag follows it. */
+    setManifest(m: unknown): void;
+    /** Makes the manifest URL answer 302 to `location` (`null` restores it). */
+    setRedirect(location: string | null): void;
+    /** The requests received, in order (absent headers omitted). */
+    requests: FakeMarketplaceRequest[];
+    stop(): Promise<void>;
+}
+/**
+ * A fake marketplace: `GET /marketplace.json` serves the current manifest (`application/json`) with a
+ * strong ETag (sha1 of the content); 304 when `If-None-Match` equals it. Other paths 404.
+ */
+export declare function startFakeMarketplace(opts: {
+    manifest: unknown;
+}): Promise<FakeMarketplace>;

package/dist/fake-marketplace.js

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto";
+import { createServer } from "node:http";
+/**
+ * A fake marketplace: `GET /marketplace.json` serves the current manifest (`application/json`) with a
+ * strong ETag (sha1 of the content); 304 when `If-None-Match` equals it. Other paths 404.
+ */
+export async function startFakeMarketplace(opts) {
+    let body = "";
+    let etag = "";
+    let redirect = null;
+    const setManifest = (m) => {
+        body = typeof m === "string" ? m : JSON.stringify(m);
+        etag = `"${createHash("sha1").update(body).digest("hex")}"`;
+    };
+    setManifest(opts.manifest);
+    const requests = [];
+    const server = createServer((req, res) => {
+        if (req.method !== "GET" || (req.url ?? "").split("?")[0] !== "/marketplace.json") {
+            res.writeHead(404).end();
+            return;
+        }
+        const r = {};
+        const inm = req.headers["if-none-match"];
+        if (typeof inm === "string")
+            r.etag = inm;
+        if (typeof req.headers.authorization === "string")
+            r.authorization = req.headers.authorization;
+        requests.push(r);
+        if (redirect !== null) {
+            res.writeHead(302, { location: redirect }).end();
+            return;
+        }
+        if (inm === etag) {
+            res.writeHead(304, { etag }).end();
+            return;
+        }
+        res
+            .writeHead(200, {
+            "content-type": "application/json",
+            "content-length": String(Buffer.byteLength(body)),
+            etag,
+        })
+            .end(body);
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    return {
+        url: `http://127.0.0.1:${server.address().port}/marketplace.json`,
+        setManifest,
+        setRedirect: (l) => {
+            redirect = l;
+        },
+        requests,
+        stop: () => new Promise((resolve) => {
+            server.closeAllConnections();
+            server.close(() => resolve());
+        }),
+    };
+}

package/dist/fake-mcp-server.d.ts

@@ -0,0 +1,134 @@
+import { type CallToolResult, type ElicitRequestFormParams, type ElicitRequestURLParams, type ElicitResult, type GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
+/** 工具处理函数抛出它 → 服务以 JSON-RPC 错误（该 code 与消息）响应，而不是 `isError` 结果。 */
+export declare class FakeMcpRpcError extends Error {
+    readonly code: number;
+    /** JSON-RPC 错误的 `data`（如 `-32042` URL elicitation 的 `{ elicitations: [...] }`）。 */
+    readonly data?: unknown;
+    constructor(code: number, message: string, 
+    /** JSON-RPC 错误的 `data`（如 `-32042` URL elicitation 的 `{ elicitations: [...] }`）。 */
+    data?: unknown);
+}
+/** 工具处理函数收到的请求信息（头名一律小写）。 */
+export interface FakeMcpCallInfo {
+    name: string;
+    args: Record<string, unknown>;
+    headers: Record<string, string>;
+}
+export interface FakeMcpTool {
+    name: string;
+    title?: string;
+    /** 不给时清单里不带 description（测试「缺描述」的映射）。 */
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    annotations?: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
+    /**
+     * 返回工具结果。可模拟慢（await 一段时间）、报错（返回 `isError: true`，或抛 `McpError` 得到 JSON-RPC 错误）、
+     * 回显请求头（`info.headers`）、超大输出。缺省返回 `ok`。
+     * `ctx.notifyToolsChanged()` 在本次调用的响应流里发 `notifications/tools/list_changed`（需 `sseResponses`）。
+     */
+    handler?: (info: FakeMcpCallInfo, ctx: FakeMcpHandlerContext) => CallToolResult | Promise<CallToolResult>;
+}
+/** 工具处理函数的第二个参数。 */
+export interface FakeMcpHandlerContext {
+    /** 发一条 `notifications/tools/list_changed`（与本次调用关联，经响应的 SSE 流送达）。 */
+    notifyToolsChanged(): Promise<void>;
+    /**
+     * 向客户端发 `elicitation/create`（经本次调用的 SSE 流）并等待答复（需 `sessions`）。客户端没有声明
+     * elicitation 能力时抛错（SDK 的能力检查）。每次调用记入 `FakeMcpServer.elicitations`。
+     */
+    elicit(params: ElicitRequestFormParams | ElicitRequestURLParams): Promise<ElicitResult>;
+}
+/** 提示模板（prompts 能力）。 */
+export interface FakeMcpPrompt {
+    name: string;
+    title?: string;
+    description?: string;
+    arguments?: {
+        name: string;
+        description?: string;
+        required?: boolean;
+    }[];
+    /** 渲染：返回消息（缺省一条 user 文本 `prompt <name> <args JSON>`）。可抛 `FakeMcpRpcError`。 */
+    render?: (args: Record<string, string>, headers: Record<string, string>) => GetPromptResult["messages"];
+}
+export interface FakeMcpResource {
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType?: string;
+    text?: string;
+    /** base64。 */
+    blob?: string;
+}
+/** 收到的一个 HTTP 请求（JSON-RPC 方法名与请求头）。 */
+export interface FakeMcpRequest {
+    httpMethod: string;
+    /** JSON-RPC 方法名；批量 / 无法解析时为 undefined。 */
+    method: string | undefined;
+    headers: Record<string, string>;
+}
+export interface FakeMcpServerOptions {
+    tools: FakeMcpTool[];
+    /** 给出时声明 resources 能力（空数组也算支持）。 */
+    resources?: FakeMcpResource[];
+    /** 给出时声明 prompts 能力（空数组也算支持）。 */
+    prompts?: FakeMcpPrompt[];
+    /**
+     * 有状态模式（`Mcp-Session-Id`，SSE 响应）：同一会话的请求由同一个 SDK `Server` 处理，服务端发起的请求
+     * （elicitation）的答复才能送回发起它的调用。缺省无状态。
+     */
+    sessions?: boolean;
+    /** 要求 `Authorization: Bearer <token>`，不符 → HTTP 401。 */
+    requireBearer?: string;
+    /** 自定义 bearer 校验（如交给假授权服务器的 `verify`）：返回 false → HTTP 401。与 `requireBearer` 二选一。 */
+    verifyBearer?: (token: string) => boolean;
+    /**
+     * OAuth 受保护资源（RFC 9728）：401 响应带 `WWW-Authenticate: Bearer`。`advertise: "header"` 时元数据放在非标准
+     * 路径、只经 `resource_metadata` 参数告知；`"well-known"` 时元数据只在
+     * `/.well-known/oauth-protected-resource/mcp`，401 不带该参数。
+     */
+    protectedResource?: {
+        authorizationServers: string[];
+        scopesSupported?: string[];
+        advertise: "header" | "well-known";
+    };
+    /** 前 n 个 HTTP 请求无条件返回 401（模拟凭据过期后刷新）。 */
+    unauthorizedTimes?: number;
+    /** 每次工具调用（在处理函数之前）调用。 */
+    onCall?: (info: FakeMcpCallInfo) => void;
+    /**
+     * 在 MCP 处理之前拦截 HTTP 请求：返回 `{ status, body, location? }` 时直接以该状态与正文响应（模拟网关报错、
+     * 正文回显请求头、重定向等），返回 undefined 时正常处理。
+     */
+    intercept?: (req: FakeMcpRequest & {
+        body: unknown;
+    }) => {
+        status: number;
+        body: string;
+        location?: string;
+    } | undefined;
+    /**
+     * 以 SSE 流响应 POST（缺省为 JSON 响应）。只有 SSE 响应能在调用途中带上服务端通知（如 list_changed）。
+     */
+    sseResponses?: boolean;
+}
+export interface FakeMcpServer {
+    /** MCP 端点（`http://127.0.0.1:<port>/mcp`）。 */
+    url: string;
+    /** 工具调用记录（按到达顺序）。 */
+    calls: FakeMcpCallInfo[];
+    /** 全部 HTTP 请求（含被 401 拒绝的）。 */
+    requests: FakeMcpRequest[];
+    /** 服务发起的 elicitation 与客户端的答复（答复前中止 / 会话关闭时 `result` 为 `"error"`）。 */
+    elicitations: {
+        params: ElicitRequestFormParams | ElicitRequestURLParams;
+        result?: ElicitResult | "error";
+    }[];
+    stop(): Promise<void>;
+}
+/**
+ * 本地假 MCP 服务（Streamable HTTP，无状态模式，缺省 JSON 响应，`sseResponses` 时 SSE）：每个 HTTP 请求新建一个 SDK `Server` 处理，
+ * 监听 127.0.0.1 随机端口。GET（独立 SSE 流）与 DELETE（结束会话）返回 405，客户端按规范忽略。
+ */
+export declare function startFakeMcpServer(opts: FakeMcpServerOptions): Promise<FakeMcpServer>;

package/dist/fake-mcp-server.js

@@ -0,0 +1,308 @@
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CallToolRequestSchema, ErrorCode, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+/** 工具处理函数抛出它 → 服务以 JSON-RPC 错误（该 code 与消息）响应，而不是 `isError` 结果。 */
+export class FakeMcpRpcError extends Error {
+    code;
+    data;
+    constructor(code, message, 
+    /** JSON-RPC 错误的 `data`（如 `-32042` URL elicitation 的 `{ elicitations: [...] }`）。 */
+    data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = "FakeMcpRpcError";
+    }
+}
+const headersOf = (req) => {
+    const out = {};
+    for (const [k, v] of Object.entries(req.headers)) {
+        if (v !== undefined)
+            out[k] = Array.isArray(v) ? v.join(", ") : v;
+    }
+    return out;
+};
+const readBody = (req) => new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+});
+const send = (res, status, body, location, extra = {}) => {
+    res.writeHead(status, {
+        "content-type": "text/plain",
+        ...(location !== undefined && { location }),
+        ...extra,
+    });
+    res.end(body);
+};
+/** 受保护资源元数据的两个位置（见 `FakeMcpServerOptions.protectedResource`）。 */
+const PRM_HEADER_PATH = "/meta/resource.json";
+const PRM_WELL_KNOWN_PATH = "/.well-known/oauth-protected-resource/mcp";
+/**
+ * 本地假 MCP 服务（Streamable HTTP，无状态模式，缺省 JSON 响应，`sseResponses` 时 SSE）：每个 HTTP 请求新建一个 SDK `Server` 处理，
+ * 监听 127.0.0.1 随机端口。GET（独立 SSE 流）与 DELETE（结束会话）返回 405，客户端按规范忽略。
+ */
+export async function startFakeMcpServer(opts) {
+    const calls = [];
+    const requests = [];
+    const elicitations = [];
+    /** 有状态模式下的会话（按 `Mcp-Session-Id`）。 */
+    const sessions = new Map();
+    let rejected = 0;
+    const mcpServer = (headers) => {
+        const server = new Server({ name: "fake-mcp", version: "1.0.0" }, {
+            capabilities: {
+                tools: { listChanged: true },
+                ...(opts.resources !== undefined && { resources: {} }),
+                ...(opts.prompts !== undefined && { prompts: {} }),
+            },
+        });
+        server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: opts.tools.map((t) => ({
+                name: t.name,
+                ...(t.title !== undefined && { title: t.title }),
+                ...(t.description !== undefined && { description: t.description }),
+                inputSchema: (t.inputSchema ?? { type: "object", properties: {} }),
+                ...(t.annotations !== undefined && { annotations: t.annotations }),
+                ...(t._meta !== undefined && { _meta: t._meta }),
+            })),
+        }));
+        server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
+            const tool = opts.tools.find((t) => t.name === req.params.name);
+            if (!tool)
+                throw new McpError(ErrorCode.InvalidParams, `Unknown tool ${req.params.name}`);
+            const info = {
+                name: req.params.name,
+                args: (req.params.arguments ?? {}),
+                headers,
+            };
+            calls.push(info);
+            opts.onCall?.(info);
+            if (!tool.handler)
+                return { content: [{ type: "text", text: "ok" }] };
+            try {
+                return await tool.handler(info, {
+                    notifyToolsChanged: () => extra.sendNotification({ method: "notifications/tools/list_changed" }),
+                    elicit: async (params) => {
+                        const entry = { params };
+                        elicitations.push(entry);
+                        try {
+                            entry.result = await server.elicitInput(params, {
+                                relatedRequestId: extra.requestId,
+                            });
+                            return entry.result;
+                        }
+                        catch (e) {
+                            entry.result = "error";
+                            throw e;
+                        }
+                    },
+                });
+            }
+            catch (e) {
+                if (e instanceof FakeMcpRpcError)
+                    throw new McpError(e.code, e.message, e.data);
+                throw e;
+            }
+        });
+        if (opts.prompts !== undefined) {
+            const prompts = opts.prompts;
+            server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+                prompts: prompts.map((p) => ({
+                    name: p.name,
+                    ...(p.title !== undefined && { title: p.title }),
+                    ...(p.description !== undefined && { description: p.description }),
+                    ...(p.arguments !== undefined && { arguments: p.arguments }),
+                })),
+            }));
+            server.setRequestHandler(GetPromptRequestSchema, async (req) => {
+                const p = prompts.find((x) => x.name === req.params.name);
+                if (!p)
+                    throw new McpError(ErrorCode.InvalidParams, `Unknown prompt ${req.params.name}`);
+                const args = (req.params.arguments ?? {});
+                try {
+                    return {
+                        ...(p.description !== undefined && { description: p.description }),
+                        messages: p.render
+                            ? p.render(args, headers)
+                            : [
+                                {
+                                    role: "user",
+                                    content: {
+                                        type: "text",
+                                        text: `prompt ${p.name} ${JSON.stringify(args)}`,
+                                    },
+                                },
+                            ],
+                    };
+                }
+                catch (e) {
+                    if (e instanceof FakeMcpRpcError)
+                        throw new McpError(e.code, e.message, e.data);
+                    throw e;
+                }
+            });
+        }
+        if (opts.resources !== undefined) {
+            const resources = opts.resources;
+            server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+                resources: resources.map((r) => ({
+                    uri: r.uri,
+                    name: r.name,
+                    ...(r.description !== undefined && { description: r.description }),
+                    ...(r.mimeType !== undefined && { mimeType: r.mimeType }),
+                })),
+            }));
+            server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+                const r = resources.find((x) => x.uri === req.params.uri);
+                if (!r)
+                    throw new McpError(ErrorCode.InvalidParams, `Resource not found: ${req.params.uri}`);
+                return {
+                    contents: [
+                        r.blob !== undefined
+                            ? {
+                                uri: r.uri,
+                                blob: r.blob,
+                                ...(r.mimeType !== undefined && { mimeType: r.mimeType }),
+                            }
+                            : {
+                                uri: r.uri,
+                                text: r.text ?? "",
+                                ...(r.mimeType !== undefined && { mimeType: r.mimeType }),
+                            },
+                    ],
+                };
+            });
+        }
+        return server;
+    };
+    let base = "";
+    const prm = opts.protectedResource;
+    const unauthorized = (res) => {
+        const challenge = prm?.advertise === "header"
+            ? `Bearer resource_metadata="${base}${PRM_HEADER_PATH}"`
+            : prm
+                ? `Bearer realm="fake-mcp"`
+                : undefined;
+        send(res, 401, "Unauthorized", undefined, challenge === undefined ? {} : { "www-authenticate": challenge });
+    };
+    const handle = async (req, res) => {
+        const path = new URL(req.url ?? "/", base).pathname;
+        if (prm && req.method === "GET") {
+            const at = prm.advertise === "header" ? PRM_HEADER_PATH : PRM_WELL_KNOWN_PATH;
+            if (path === at) {
+                res.writeHead(200, { "content-type": "application/json" });
+                res.end(JSON.stringify({
+                    resource: `${base}/mcp`,
+                    authorization_servers: prm.authorizationServers,
+                    bearer_methods_supported: ["header"],
+                    ...(prm.scopesSupported !== undefined && { scopes_supported: prm.scopesSupported }),
+                }));
+                return;
+            }
+            if (path.startsWith("/.well-known/") || path === PRM_HEADER_PATH) {
+                return send(res, 404, "Not Found");
+            }
+        }
+        const headers = headersOf(req);
+        const raw = req.method === "POST" ? await readBody(req) : "";
+        let body;
+        try {
+            body = raw === "" ? undefined : JSON.parse(raw);
+        }
+        catch {
+            body = raw;
+        }
+        const method = typeof body === "object" && body !== null && !Array.isArray(body)
+            ? body.method
+            : undefined;
+        const entry = { httpMethod: req.method ?? "GET", method, headers };
+        requests.push(entry);
+        if (rejected < (opts.unauthorizedTimes ?? 0)) {
+            rejected++;
+            return unauthorized(res);
+        }
+        if (opts.requireBearer !== undefined &&
+            headers.authorization !== `Bearer ${opts.requireBearer}`) {
+            return unauthorized(res);
+        }
+        if (opts.verifyBearer) {
+            const m = /^Bearer (.+)$/.exec(headers.authorization ?? "");
+            if (!m || !opts.verifyBearer(m[1]))
+                return unauthorized(res);
+        }
+        const over = opts.intercept?.({ ...entry, body });
+        if (over)
+            return send(res, over.status, over.body, over.location);
+        if (opts.sessions)
+            return handleSession(req, res, headers, body);
+        if (req.method !== "POST")
+            return send(res, 405, "Method Not Allowed");
+        const server = mcpServer(headers);
+        // 不给 sessionIdGenerator = 无状态模式
+        const transport = new StreamableHTTPServerTransport({
+            enableJsonResponse: opts.sseResponses !== true,
+        });
+        res.on("close", () => {
+            void transport.close();
+            void server.close();
+        });
+        // exactOptionalPropertyTypes 下 SDK 自身的 Transport 类型不兼容（onclose 可为 undefined），按 SDK 文档用法转型
+        await server.connect(transport);
+        await transport.handleRequest(req, res, body);
+    };
+    /** 有状态模式：按 `Mcp-Session-Id` 路由到会话的 transport；initialize 新建会话。 */
+    const handleSession = async (req, res, headers, body) => {
+        const sid = headers["mcp-session-id"];
+        const existing = sid === undefined ? undefined : sessions.get(sid);
+        if (existing) {
+            await existing.handleRequest(req, res, body);
+            return;
+        }
+        if (sid !== undefined)
+            return send(res, 404, "Session not found");
+        if (req.method !== "POST")
+            return send(res, 405, "Method Not Allowed");
+        const server = mcpServer(headers);
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: (id) => {
+                sessions.set(id, transport);
+            },
+        });
+        transport.onclose = () => {
+            if (transport.sessionId)
+                sessions.delete(transport.sessionId);
+            void server.close();
+        };
+        await server.connect(transport);
+        await transport.handleRequest(req, res, body);
+    };
+    const http = createServer((req, res) => {
+        handle(req, res).catch((e) => {
+            if (!res.headersSent)
+                send(res, 500, String(e));
+            else
+                res.end();
+        });
+    });
+    await new Promise((resolve) => http.listen(0, "127.0.0.1", resolve));
+    const { port } = http.address();
+    base = `http://127.0.0.1:${port}`;
+    return {
+        url: `${base}/mcp`,
+        calls,
+        requests,
+        elicitations,
+        stop: () => new Promise((resolve, reject) => {
+            for (const t of sessions.values())
+                void t.close();
+            sessions.clear();
+            http.closeAllConnections();
+            http.close((err) => (err ? reject(err) : resolve()));
+        }),
+    };
+}

package/dist/fake-model-server.d.ts

@@ -0,0 +1,28 @@
+export interface FakeRequest {
+    path: string;
+    body: unknown;
+    headers: Record<string, string>;
+}
+export type FakeResponse = {
+    status: number;
+    json: unknown;
+    headers?: Record<string, string>;
+} | {
+    status: 200;
+    sse: {
+        event?: string;
+        data: string;
+    }[];
+    delayMs?: number;
+    /** 写完全部事件后不结束响应（连接保持打开），用于验证客户端在终止事件后自行停止读取。 */
+    keepOpen?: boolean;
+} | {
+    stall: true;
+};
+export interface FakeModelServer {
+    url: string;
+    requests: FakeRequest[];
+    stop(): Promise<void>;
+}
+/** 本地假模型服务：供插件用原生协议编写夹具。 */
+export declare function startFakeModelServer(routes: (req: FakeRequest) => FakeResponse): Promise<FakeModelServer>;

package/dist/fake-model-server.js

@@ -0,0 +1,67 @@
+import { createServer } from "node:http";
+/** 本地假模型服务：供插件用原生协议编写夹具。 */
+export async function startFakeModelServer(routes) {
+    const requests = [];
+    const server = createServer((req, res) => {
+        const chunks = [];
+        req.on("data", (c) => chunks.push(c));
+        req.on("end", () => {
+            const raw = Buffer.concat(chunks).toString("utf8");
+            let body = raw;
+            try {
+                body = raw === "" ? undefined : JSON.parse(raw);
+            }
+            catch {
+                body = raw;
+            }
+            const headers = {};
+            for (const [k, v] of Object.entries(req.headers)) {
+                if (v !== undefined)
+                    headers[k] = Array.isArray(v) ? v.join(", ") : v;
+            }
+            const fake = { path: req.url ?? "/", body, headers };
+            requests.push(fake);
+            let out;
+            try {
+                out = routes(fake);
+            }
+            catch (e) {
+                res.writeHead(500, { "content-type": "application/json" });
+                res.end(JSON.stringify({ error: String(e) }));
+                return;
+            }
+            if ("stall" in out) {
+                res.writeHead(200, { "content-type": "text/event-stream" });
+                res.flushHeaders();
+                return;
+            }
+            if ("json" in out) {
+                res.writeHead(out.status, { ...out.headers, "content-type": "application/json" });
+                res.end(JSON.stringify(out.json));
+                return;
+            }
+            res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache" });
+            const payload = out.sse
+                .map((e) => `${e.event !== undefined ? `event: ${e.event}\n` : ""}data: ${e.data}\n\n`)
+                .join("");
+            const finish = out.keepOpen ? () => res.write(payload) : () => res.end(payload);
+            if (out.delayMs) {
+                const t = setTimeout(finish, out.delayMs);
+                res.on("close", () => clearTimeout(t));
+            }
+            else {
+                finish();
+            }
+        });
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const { port } = server.address();
+    return {
+        url: `http://127.0.0.1:${port}`,
+        requests,
+        stop: () => new Promise((resolve) => {
+            server.close(() => resolve());
+            server.closeAllConnections();
+        }),
+    };
+}

package/dist/fake-npm-registry.d.ts

@@ -0,0 +1,59 @@
+/** 假 registry 上的一个包版本。 */
+export interface FakeNpmPackage {
+    /** npm 包名（可带 scope）。 */
+    name: string;
+    version: string;
+    tgz: Uint8Array;
+    /** 元数据里的 `dist.integrity`；不给 = 按 tgz 算出的 sha512（可故意给错）。 */
+    integrity?: string;
+    /** 元数据里的 `dist.tarball`；不给 = 本服务上的地址（给别的源测「不同源」）。 */
+    tarballUrl?: string;
+    /** tarball 地址先 302 到真实地址（测「不跟随重定向」）。 */
+    redirectTarball?: boolean;
+    /** 打上的 dist-tag（如 `latest`）；同名包没有任何版本带 `latest` 时取最后一个版本。 */
+    tags?: string[];
+    /**
+     * The body of `GET /-/npm/v1/attestations/<name>@<version>` (e.g. from
+     * {@link npmProvenanceAttestations}); not given = 404, as for a package published without provenance.
+     */
+    attestations?: unknown;
+}
+export interface FakeNpmRegistry {
+    /** registry 基址 `http://127.0.0.1:<port>`。 */
+    url: string;
+    /** 收到的请求路径（含查询串），按到达顺序。 */
+    requests: string[];
+    /** 收到的 `authorization` 请求头（没有为 undefined），与 {@link requests} 一一对应。 */
+    authorizations: (string | undefined)[];
+    /** The `accept` request header of each request (undefined when absent), as {@link requests}. */
+    accepts: (string | undefined)[];
+    stop(): Promise<void>;
+}
+/**
+ * An attestations answer in the shape npm serves (`{ attestations: [...] }`): the npm publish
+ * attestation and the SLSA v1 provenance, each a sigstore bundle with a DSSE envelope whose payload
+ * is a base64 in-toto statement about `pkg:npm/<name>@<version>` (subject digest = the tgz's sha512,
+ * or `subjectSha512` to make it about another tarball). The signatures are placeholders (the kernel
+ * does not verify them). `predicate` replaces the SLSA predicate (to test missing fields).
+ */
+export declare function npmProvenanceAttestations(o: {
+    name: string;
+    version: string;
+    tgz: Uint8Array;
+    repository: string;
+    commit: string;
+    workflow?: string;
+    ref?: string;
+    subjectSha512?: string;
+    predicate?: unknown;
+}): unknown;
+/**
+ * A fake npm registry: `GET /<name>` (a scoped package written as npm does, `@scope%2fname`; an
+ * unencoded `/` is accepted too) returns the packument (`versions[v].dist.{tarball, integrity}` and
+ * `dist-tags`), `GET /<name>/-/<file>.tgz` returns the tarball, and
+ * `GET /-/npm/v1/attestations/<name>@<version>` returns that version's `attestations` (404 when it
+ * has none). Unknown packages are 404.
+ */
+export declare function startFakeNpmRegistry(opts: {
+    packages: FakeNpmPackage[];
+}): Promise<FakeNpmRegistry>;