DiAL/openspec/specs/single-executable-packaging/spec.md

Purpose

定义将 Vite 前端资源与 Bun 后端打包为单个 standalone executable 的生产构建、运行配置和验证要求。

Requirements

Requirement: 生产构建顺序

生产构建 MUST 在编译 Bun 后端 executable 之前先构建 Vite 前端。

Scenario: 运行生产构建

• WHEN 开发者运行生产构建命令
• THEN 系统 MUST 在调用 Bun standalone executable 编译之前生成前端静态资源

Scenario: 前端构建失败

• WHEN 前端生产构建失败
• THEN 系统 MUST 停止生产构建，且不能输出 stale executable

Requirement: 构建生成确定性

生产构建 SHALL 以稳定顺序生成嵌入静态资源清单，减少重复构建产生无意义差异。

Scenario: 生成静态资源清单

• WHEN 生产构建扫描 Vite 输出目录并生成嵌入资源模块
• THEN 资源条目 SHALL 按稳定顺序输出

Scenario: 重复构建相同前端产物

• WHEN Vite 输出内容未变化且生产构建重复运行
• THEN 生成的嵌入资源模块 SHALL 保持语义一致且不依赖文件系统遍历顺序

Requirement: 单 executable 输出

生产构建 SHALL 输出一个 standalone executable，其中包含 Bun 后端、必要 server 依赖和构建后的前端资源。

Scenario: 在目标机器运行 executable

• WHEN 生成的 executable 在兼容目标平台上运行
• THEN 它 SHALL 启动全栈应用，且不要求目标机器安装 Node.js、Bun、Vite 或 node_modules

Scenario: 服务嵌入的前端

• WHEN executable 收到前端根路径请求
• THEN 它 SHALL 从 executable 内包含的资源服务前端，且不需要外部 dist/ 目录

Scenario: 服务嵌入 demo API 和页面

• WHEN 生成的 executable 启动，且浏览器打开前端根路径
• THEN 页面 SHALL 展示同一个 executable 进程中 /api/demo 返回的数据

Requirement: 外部运行时配置

executable MUST 将环境相关运行时配置保留在嵌入的前端和 server bundle 之外。

Scenario: 修改监听端口

• WHEN 操作者修改受支持的 port 配置
• THEN 同一个 executable SHALL 在不重新构建的情况下监听新端口

Scenario: 缺少可选配置

• WHEN 可选运行时配置被省略
• THEN executable SHALL 使用文档化的默认值

Requirement: 构建验证

项目 SHALL 提供验证，证明生产 executable 可以服务 API、健康检查、静态资源和 SPA fallback 路由，并且完整验证 MUST 针对当前源码重新构建后的 executable 运行。

Scenario: 验证 executable 路由

• WHEN 构建验证针对生成的 executable 运行
• THEN 它 SHALL 检查 /api/demo、/health、前端根路径、静态资源、未知 API、未知静态资源和前端 fallback 请求

Scenario: 验证生产模式和响应头

• WHEN 构建验证针对生成的 executable 运行
• THEN 它 SHALL 检查 demo 响应处于 production runtime mode，并验证代表性 HTML、JSON 和静态资源响应的缓存或低风险安全 headers

Scenario: 完整验证重新构建 executable

• WHEN 开发者运行完整验证命令
• THEN 系统 MUST 先基于当前源码执行生产构建，再对新生成的 executable 运行 smoke test

Scenario: 验证失败

• WHEN 任一代表性生产路由、响应头、生产模式或构建阶段检查失败
• THEN 验证 SHALL 使构建或测试命令失败