@adep/web-container — AgentDeploy 浏览器原生开发环境 SDK

浏览器端开发/运行环境 SDK（任务单 FN-012）：虚拟文件系统 + 进程/shell + JS 运行时适配接口 + npm-relay 客户端。对标 WebContainers API——Node 可测、浏览器可跑。

npm install @adep/web-container
# 或
pnpm add @adep/web-container

能力总览

| 能力 | 说明 | | ------------------ | --------------------------------------------------- | | 虚拟文件系统 (VFS) | 内存文件树：读写 / 查找 / 变更通知 | | 进程 / shell | 在虚拟环境中执行命令、管道输入输出 | | 运行时适配接口 | 用适配器接宿主运行时（预览 / 沙箱执行） | | npm-relay 客户端 | 经平台 npm-relay 安装 / 解析前端依赖 | | 浏览器内跑测试 | test 命令 + describe/it/expect 最小集（FN-022） |

用法

import { bootstrap } from '@adep/web-container'

const container = bootstrap({ npmRelayBaseUrl: '/api/v1/npm-relay' })

await container.mount({
  'index.test.ts': "describe('a', () => { it('一', () => expect(1).toBe(1)) })",
})
await container.writeFile('notes.txt', 'hi')
console.log(await container.readFile('notes.txt'))
console.log(await container.run('test')) // → ✓ a › 一 … 汇总：1 passed

在浏览器里跑测试（FN-022）

终端里的 test 是浏览器内跑的：不经过服务端，不需要本机 Node。

$ test              # 当前目录递归收集
$ test src/utils    # 指定目录
$ test a.test.ts    # 指定单文件

| 口径 | 约定 | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 收集 | 文件名以 .test.ts / .spec.ts 结尾（.js / .mjs / .cjs 同样收）；递归、字典序；跳过 node_modules/、.git/、.adep/ 与 .d.ts | | 全局 | describe / it（别名 test）/ expect / beforeEach / afterEach 由沙箱注入，测试文件不 import 测试框架 | | 断言 | toBe（Object.is）/ toEqual（深比较）/ toBeTruthy / toBeFalsy / toBeNull / toBeUndefined / toBeDefined / toContain / toHaveLength / toThrow，均支持 .not | | 退出码 | 全部通过 0；有断言失败、有加载错误、或用例数为 0 → 1；路径不存在 → 1（写 stderr） | | 日志 | 用例里的 console.log 随该文件的报告按行展示（│ 前缀） | | 超时 | 单条用例默认 5s（浏览器主线程不能被一个卡住的 await 放任成挂死的终端） |

TypeScript：测试文件可以照常写类型标注。strip-types.ts 会把它擦成可 new Function 求值的 JS ——对纯 JS 逐字节恒等、擦除区间保留换行（行号不漂）。擦除器不引第三方依赖，且与 @adep/runtime 的宿主能力探测（Bun.Transpiler / node:module）无关：同一份文件在浏览器与 Node 单测里必须同语义。

• 擦除子集：interface、type 别名、import type / export type、参数 / 返回值 / 变量 / 类成员标注、解构参数标注、可选参数 ?:、非空断言 !、as / satisfies、声明位泛型、 implements、类成员 TS 修饰符。
• 明确不支持（抛 UnsupportedTsSyntaxError，报为该文件「加载失败」）：enum、namespace。
• 判不准就不擦：漏擦的代价是求值期一个 SyntaxError（如实上报），而不是静默改变语义。

边界：测试与 node <file> 共用同一条求值路径（worker-runtime.evaluateModuleSource）， 所以沙箱既有的限制都在这里生效——export 语句不被支持（入口式函数文件请直接用 node 调试）， cloud.* 在测试里可用与否取决于 FN-023 的进度（本包只保证「无 ctx 的纯函数测试」可跑）。 完整 vitest 兼容（快照 / 模块 mock / 覆盖率）不在范围内。

说明

• 面向浏览器，同时成 Node 可测；依赖 @adep/types 提供类型契约。

• 需要浏览器内作为 <script> 全局加载的 IIFE 变体见 scripts.build:sdk（dist/web-container.iife.js，globalName = AdepWebContainer）。