# CLI 内部架构

Zig 分发器、配置、服务器、编译、HMR、所有权与贡献测试。

<span id="recorrido-de-una-invocación"></span>

<span class="section-anchor" id="section-1"></span>

## 一次调用的执行路径

npm 启动器识别平台并执行二进制文件。`main.zig` 接收参数，将第一个 token 分发到命令模块。各命令决定如何解析其余参数，因此没有统一的全局选项语法。

项目命令通过加载器取得 `WuConfig` 结构。该配置把字符串保存在自己的 arena 中，并通过 `deinit` 释放内存，从而避免返回指向已释放 JSON 缓冲区的视图。目录发现是另一种配置来源，不是始终与显式文件合并的步骤。

<span id="mapa-de-módulos"></span>

<span class="section-anchor" id="section-2"></span>

## 模块索引

| 源码路径 | 职责 |
| --- | --- |
| `src/main.zig` | 命令分发、版本和 Zig 测试汇总 |
| `src/cli/` | 帮助、横幅、终端模式、菜单和提示 |
| `src/config/config.zig` | 解析与写入配置 |
| `src/config/discovery.zig` | 子目录项目识别规则 |
| `src/config/deps.zig` | 使用别名和本地工具链 |
| `src/commands/` | 使用场景与产物生成 |
| `src/runtime/dev_server.zig` | 监听器、路由、模块和重新加载桥接 |
| `src/runtime/compile.zig` | 选择编译器并连接守护进程 |
| `src/runtime/compiler_daemon.js` | Node 编译器与消息分帧 |
| `src/runtime/transform.zig` | 重写 import、别名和 CSS |
| `src/runtime/hypervisor/` | 监听器与前缀路由器 |
| `src/runtime/security.zig` | 路径验证和 HTTP 策略 |
| `src/orchestrator/` | Vite 开发进程与监督管理 |
| `src/util/jobobject.zig` | Windows 子进程生命周期 |

存在 `src/proxy/server.zig` 或 `src/commands/test.zig`，不能证明命令实际走这些路径。判断时应从分发器开始追踪调用，不要仅根据文件名推断能力。

`src/runtime/dev/` 分离路由、文件、导入、CSS、环境、socket 和 HMR。`module_graph.zig` 维护身份及按导入者解析；`project_fs.zig` 限制文件访问。`catalog.zig`、`semver.zig` 和 `json_doc.zig` 集中处理版本、交集及清单写入。`deploy.zig` 和 `build_cache.zig` 实现事务式本地输出替换和构建复用。

<span id="servidor-y-compilador"></span>

<span class="section-anchor" id="section-3"></span>

## 服务器与编译器

请求通过 HTTP 进入，经验证后分配给应用或 shell，再解析为文件或依赖。编译产生 JavaScript，随后将 import 改写为服务器 URL。应用身份必须贯穿整个流程，才能正确解析其依赖、样式和工具链。

守护进程通过管道维护通信通道。请求包含标识符、编译类型、文件、loader、长度和应用目录。响应返回相同标识符，并传输代码或错误。长度用于确定消息边界，错误被压缩为协议中的单行。

协议按标识符多路复用请求。`compile_pool.zig` 管理带时限的多个守护进程，`compile_warmup.zig` 预编译导入；Angular 复用增量编译器。VFS、旧转换池和被禁用的原生 JSX 转换器已移除。

守护进程的标准输出专供协议使用。插件意外输出消息可能破坏帧对齐，因此守护进程会把多个 `console` 日志级别重定向到日志文件。父进程检查响应标识符，并在对话错位时重新启动通信。

<span id="watcher-y-router"></span>

<span class="section-anchor" id="section-4"></span>

## 监听器与路由器

hypervisor 在路由器中注册应用前缀，并监听项目目录，整合文件事件机制和内容缓存。需要注意其所有权关系：服务器按值返回后，指向内部字段的指针必须重新绑定到最终位置。`bindRunning` 用于处理这一生命周期关系。

服务器协调停止、关闭连接和守护进程。在 Windows 上，Job Objects 帮助确保子进程不会在所属进程结束后继续存活。这项功能需要在真实操作系统中测试；检查源码不等于已经观察到所有平台都正确清理进程。

<span id="construir-y-probar-una-modificación"></span>

<span class="section-anchor" id="section-5"></span>

## 构建并测试修改

```bash
zig build
zig build test --summary all
npm test
```

`build.zig` 定义编译和 Zig 测试步骤。`npm test` 执行 `scripts/check-invariants.mjs` 的不变量检查及 `tests/*.test.cjs`，验证启动器、守护进程协议和 doctor 退出状态等约定。请使用刚构建的二进制文件运行测试。测试摘要可确认实际执行和跳过的用例；验证生成应用仍需要浏览器测试。

`main.zig` 显式导入包含测试的模块；不变量检查测试聚合器和命令参考。`npm run test:fuzz` 测试 HTTP、WebSocket、路径、JSON、SemVer 和 import 解析器。发布使用 ReleaseSafe、校验和与可复现重建。

修改协议时，应测试分片消息、同一数据块中的多个请求、长错误信息和交叉标识符。修改应用骨架时，需要生成、编译并在浏览器中挂载。修改 HTTP 时，应测试路径、方法、缺失资源以及最终响应头。

<span id="referencia-de-implementación"></span>

<span class="section-anchor" id="section-6"></span>

## 实现参考

- `wu-cli/src/main.zig`
- `wu-cli/src/runtime/dev/`
- `wu-cli/src/runtime/compile_pool.zig`
- `wu-cli/src/runtime/compiler_daemon.js`
- `wu-cli/src/runtime/module_graph.zig`
- `wu-cli/src/runtime/project_fs.zig`
- `wu-cli/src/commands/deploy.zig`
- `wu-cli/scripts/check-invariants.mjs`
- `wu-cli/src/fuzz.zig`