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

Purpose

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

Requirements

Requirement: 生产构建顺序

生产构建 MUST 通过 Bun.build 的 HTML import 识别机制一步完成前端资源打包和后端编译。

Scenario: 运行生产构建

• WHEN 开发者运行生产构建命令
• THEN 系统 MUST 调用 Bun.build，自动识别 server 入口中的 HTML import 并完成前端 bundling 和后端编译

Scenario: 前端 bundling 失败

• WHEN Bun.build 在处理 HTML import 中的前端资源时失败
• THEN 系统 MUST 停止生产构建，且不能输出 stale executable

Requirement: 单 executable 输出

生产构建 SHALL 输出一个 standalone executable，其中包含 Bun 后端和通过 HTML import manifest 嵌入的前端资源。构建流程 SHALL 不再生成项目自定义中间产物目录，构建失败时 SHALL 不保留 stale executable。

Scenario: 在目标机器运行 executable

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

Scenario: 服务嵌入的前端

• WHEN executable 收到前端根路径请求
• THEN 它 SHALL 通过 Bun 内置的 HTML import manifest 机制服务前端资源，且不需要外部 dist/ 目录

Scenario: 服务嵌入 API 和页面

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

Scenario: 构建成功不生成自定义中间产物

• WHEN 生产构建成功完成并输出 executable
• THEN 系统 SHALL 不生成 .build/ 静态资源清单或 server entry 中间产物

Scenario: 构建失败时不保留 stale executable

• WHEN 生产构建在任意步骤失败
• THEN 系统 SHALL 不输出上一次构建遗留的 stale executable

Requirement: 外部运行时配置

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

Scenario: 修改监听端口

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

Scenario: 缺少可选配置

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

Requirement: 构建验证

项目 SHALL 提供 verify 命令执行质量检查和生产构建；原 smoke test 暂时移除，executable 路由验证由后续变更重新设计。

Scenario: 完整验证重新构建 executable

• WHEN 开发者运行完整验证命令
• THEN 系统 MUST 先执行质量检查，再基于当前源码执行生产构建

Scenario: 验证失败

• WHEN 质量检查或构建阶段失败
• THEN 验证 SHALL 使命令失败