@adep/web-container 0.1.0 → 0.1.1

package/README.md

@@ -10,30 +10,66 @@ pnpm add @adep/web-container
 
 ## 能力总览
 
-| 能力            | 说明                        |
-| ------------- | ------------------------- |
-| 虚拟文件系统 (VFS)  | 内存文件树：读写 / 查找 / 变更通知      |
-| 进程 / shell    | 在虚拟环境中执行命令、管道输入输出         |
-| 运行时适配接口       | 用适配器接宿主运行时（预览 / 沙箱执行）     |
-| npm-relay 客户端 | 经平台 npm-relay 安装 / 解析前端依赖 |
+| 能力               | 说明                                                |
+| ------------------ | --------------------------------------------------- |
+| 虚拟文件系统 (VFS) | 内存文件树：读写 / 查找 / 变更通知                  |
+| 进程 / shell       | 在虚拟环境中执行命令、管道输入输出                  |
+| 运行时适配接口     | 用适配器接宿主运行时（预览 / 沙箱执行）             |
+| npm-relay 客户端   | 经平台 npm-relay 安装 / 解析前端依赖                |
+| 浏览器内跑测试     | `test` 命令 + `describe/it/expect` 最小集（FN-022） |
 
 ## 用法
 
 ```ts
-import { createWebContainer } from '@adep/web-container'
+import { bootstrap } from '@adep/web-container'
 
-const container = await createWebContainer({
-  // 传入文件系统与运行时适配器
+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）
 
-await container.fs.mkdir('/hello')
-await container.fs.writeFile('/hello/index.txt', 'hi')
-const text = await container.fs.readFile('/hello/index.txt', 'utf8')
+终端里的 `test` 是**浏览器内**跑的：不经过服务端，不需要本机 Node。
+
+```bash
+$ 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`）。
-

package/dist/completion.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Shell 的 Tab 补全 API（FE-022）。
+ *
+ * 此前 `BrowserTerminal.vue` 的 `handleData` 没有 `\t` 分支，可打印过滤 `cp >= 0x20` 又把 Tab 静默吞掉
+ * ——按 Tab 什么也不发生。本文件把「补全什么」从「按键怎么处理」里拆出来，做成纯函数：
+ * - 命令位（行首且未输入 `/`）→ 补内建命令名；
+ * - 参数位 → 按 VFS 目录列表补路径，目录候选带尾部 `/`（与 bash 一致，便于继续下钻）；
+ * - `cd` 的参数只列目录。
+ *
+ * 解析与匹配全部不依赖具体 fs：调用方给一份目录条目列表（`WebContainerFsEntry[]`）即可，
+ * 因此同步（持有 `VirtualFileSystem`，如 `Shell.complete`）与异步（只有 `WebContainer`，如 IDE 终端）
+ * 两个入口共用同一套判据，不会各说各话。npm 不是 shell 内建命令（由 IDE 侧拦成 `container.install`），
+ * 故只在补全表里出现、不进 `SHELL_COMMANDS`。
+ */
+import type { WebContainerFsEntry } from '@adep/types';
+/** shell 内建命令（`shell.ts` 的 switch 分支，`help` 文案由此派生，避免两处清单漂移）。 */
+export declare const SHELL_COMMANDS: readonly ["pwd", "ls", "cat", "echo", "mkdir", "touch", "rm", "rmdir", "cp", "mv", "cd", "head", "tail", "test", "node", "js", "help"];
+/** 只在补全里出现的平台命令（由上层拦截实现，非 shell 内建）。 */
+export declare const EXTRA_COMMANDS: readonly ["npm"];
+/** 命令位可补的全部命令。 */
+export declare const COMPLETABLE_COMMANDS: readonly string[];
+/** 补全上下文（由 `parseCompletionContext` 解析出，纯数据）。 */
+export interface CompletionContext {
+    /** 被补全的 token（用户已输入的原文，含目录前缀）。 */
+    token: string;
+    /** token 在整行中的起始下标（替换区间起点，终点为行尾）。 */
+    start: number;
+    kind: 'command' | 'path';
+    /** 命令位（行首命令名）与参数位所属的命令名（路径补全据此决定要不要只列目录）。 */
+    command: string;
+    /** 路径补全时要去列出的目录（已按 cwd 解析为绝对路径）；命令位为 null。 */
+    dir: string | null;
+    /** token 里用于过滤的末级名前缀。 */
+    prefix: string;
+    /** 候选要回写时保留的目录前缀原文（如 `src/` 或 `/tmp/`）。 */
+    dirText: string;
+}
+/** 补全结果。 */
+export interface CompletionResult {
+    context: CompletionContext;
+    /** 候选（完整替换 token：含原目录前缀，目录带尾部 `/`），已按字典序。 */
+    candidates: string[];
+    /** 候选的公共前缀（用于「多候选先补到分叉点」）；无候选时等于 token。 */
+    commonPrefix: string;
+}
+/** 同步的目录列表提供者（`VirtualFileSystem` 即符合此形状）。 */
+export interface CompletionFsView {
+    listDirectory(path: string): readonly WebContainerFsEntry[];
+}
+/** 异步的目录列表提供者（`WebContainer` 即符合此形状）。 */
+export interface AsyncCompletionFsView {
+    listDirectory(path: string): Promise<readonly WebContainerFsEntry[]>;
+}
+/** 解析一行输入，得出「该补命令还是路径、去哪个目录找」。 */
+export declare function parseCompletionContext(line: string, cwd: string): CompletionContext;
+/** 给定目录条目算出候选（纯函数：同步 / 异步入口都收敛到这里）。 */
+export declare function completeWithListing(context: CompletionContext, listing: readonly WebContainerFsEntry[]): CompletionResult;
+/** 同步入口：直接持有 VFS（或任何 `listDirectory` 同步实现）时用它。 */
+export declare function completeShellInput(options: {
+    line: string;
+    cwd: string;
+    fs: CompletionFsView;
+}): CompletionResult;
+/** 异步入口：只持有 `WebContainer`（公开 API 的 `listDirectory` 是异步的）时用它。 */
+export declare function completeContainerInput(options: {
+    line: string;
+    cwd: string;
+    fs: AsyncCompletionFsView;
+}): Promise<CompletionResult>;
+/**
+ * 把候选写回输入行：替换 `[start, 行尾)` 区间。
+ * `candidate` 省略时取公共前缀（多候选补到分叉点，与 bash 行为一致）。
+ */
+export declare function applyCompletion(line: string, result: CompletionResult, candidate?: string): string;
+/** 候选的展示名（去掉目录前缀与目录尾部斜杠，终端里逐列打印时更紧凑）。 */
+export declare function candidateLabel(candidate: string): string;
+/** 供 `help` 文案派生：`内建命令：pwd ls …`。 */
+export declare function helpText(): string;

package/dist/container.d.ts

@@ -10,7 +10,9 @@
  */
 import type { WebContainer, WebContainerDirectoryTree } from '@adep/types';
 import type { CloudFetch } from '@adep/types';
+import { VirtualFileSystem } from './vfs';
 import { type JsRuntime } from './shell';
+import type { TestReport } from './test-framework';
 export interface BootstrapOptions {
     /**
      * 平台 npm 中继基础路径（浏览器端相对当前源，如 `/api/v1/npm-relay`）。
@@ -22,5 +24,22 @@ export interface BootstrapOptions {
     runtime?: JsRuntime;
     /** npm 中继网络实现（缺省 globalThis.fetch；测试注入假中继）。 */
     fetchImpl?: CloudFetch;
+    /**
+     * 注入既有 VFS 实例（FE-022）：容器默认自建内存 VFS，接持久化（`createFsPersistence`）
+     * 需要上层先拿到同一个实例去 `hydrate()`，故开此注入点。省略即原行为。
+     */
+    vfs?: VirtualFileSystem;
+    /**
+     * cwd 变化回调（FE-022）：Tab 补全要把相对路径按当前目录解析，而 `WebContainer` 公开契约
+     * 不含 cwd（见 `@adep/types` 的 `web-container.ts`），故以回调而非新增方法暴露，
+     * 避免为一个 IDE 需求改动对外 SDK 契约。
+     */
+    onCwdChange?: (cwd: string) => void;
+    /**
+     * `test` 命令跑完后的结构化报告回调（FN-022）：终端里的文本报告是主口径，
+     * IDE 侧还要一份可渲染的数据。与 `onCwdChange` 同一取向——`WebContainer` 公开契约
+     * （`@adep/types`）不含这两者，故经装配选项回灌，不为此改动对外 SDK 契约。
+     */
+    onTestResult?: (report: TestReport) => void;
 }
 export declare function bootstrap(options: BootstrapOptions): WebContainer;

package/dist/index.d.ts

@@ -16,9 +16,26 @@ export type { BootstrapOptions } from './container';
 export { VirtualFileSystem } from './vfs';
 export { Shell } from './shell';
 export type { JsRuntime, ShellResult } from './shell';
-export { createWorkerRuntime, evaluateSource } from './worker-runtime';
-export type { WorkerRuntimeOptions, WorkerLike } from './worker-runtime';
-export { createNpmClient, parseSpec } from './npm-client';
-export type { NpmClientOptions, NpmInstallResult } from './npm-client';
+export { createWorkerRuntime, evaluateSource, evaluateModuleSource } from './worker-runtime';
+export type { WorkerRuntimeOptions, WorkerLike, ModuleEvalOptions } from './worker-runtime';
+export { createNpmClient, parseSpec, DEFAULT_MAX_INSTALL_DEPTH } from './npm-client';
+export type { NpmClientOptions, NpmInstallResult, NpmInstalledPackage, NpmInstallStorage, NpmPersistence, } from './npm-client';
+export { gunzip, unpackTar, unpackNpmTarball } from './tar';
+export type { TarEntry } from './tar';
+export { ResolveError, parsePackageMeta, resolveImport, resolvePackageEntry, splitPackageSpecifier, RESOLVE_EXTENSIONS, } from './node-resolve';
+export type { ResolveFs, PackageMeta, ExportCondition } from './node-resolve';
+export { createRequire, createSandboxModuleGlobals, interopDefault, transformStaticImports, usesModuleSyntax, } from './module-loader';
+export type { ModuleCache, RequireOptions } from './module-loader';
 export * as posix from './path';
+export { snapshotVfs, restoreVfs, entriesToTree, createMemoryFsBackend, createIndexedDbFsBackend, pickDefaultFsBackend, createFsPersistence, createMemoryKvStorage, createCommandHistory, } from './persistence';
+export type { FsPersistEntry, FsPersistenceBackend, FsPersistence, FsPersistenceOptions, CommandHistory, KvStorage, } from './persistence';
+export { SHELL_COMMANDS, EXTRA_COMMANDS, COMPLETABLE_COMMANDS, parseCompletionContext, completeWithListing, completeShellInput, completeContainerInput, applyCompletion, candidateLabel, } from './completion';
+export type { CompletionContext, CompletionResult, CompletionFsView, AsyncCompletionFsView, } from './completion';
+export { stripTypes, UnsupportedTsSyntaxError } from './strip-types';
+export { createTestRunner, collectTestFiles, formatTestReport, summaryLine, exampleTestSource, TEST_FILE_PATTERN, displayPath, } from './test-runner';
+export type { TestRunnerOptions, TestRunOutcome, TestCommandPort, TestEvaluator, } from './test-runner';
+export { createTestScope, runCollectedTests, expect as expectAssertion, deepEqual, formatValue, fullName, TestAssertionError, } from './test-framework';
+export type { TestReport, TestFileResult, TestCaseResult, TestScope, TestRegistration, Expectation, } from './test-framework';
+export * from './offline';
+export * from './sim';
 export type { WebContainer, WebContainerDirectoryTree, WebContainerEventMap, WebContainerFsEntry, WebContainerProcess, } from '@adep/types';