feat: release v0.28 generic Go project scaffolding and lifecycle entry

PROGRAM.md

@@ -0,0 +1,81 @@
+# 通用 Go 项目模板
+
+从 v0.28.0-preview 起，`project new/generate/check` 提供不绑定协议与业务的工程骨架。默认只有配置、日志、依赖装配、生命周期和普通 Go 运行入口；不生成 `.api`、HTTP Handler、Swagger、业务任务，也不监听端口、连接数据库或队列。不增加第三方依赖。
+
+## 创建与运行
+
+```sh
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.28.0-preview
+go-omni project new demo --module example.com/demo
+cd demo
+go mod tidy
+go run . -check-config
+go run .                 # 默认等待 SIGINT / SIGTERM
+go build -o program .
+```
+
+目标目录必须为空；未指定 module 时使用目录名。远程安装的 CLI 将自己的固定版本写入 go.mod，无本地替换。当前通用模板要求框架 v0.28.0-preview 或更新版本。源码开发可显式 `--framework-dir /path/to/go-omni`，不会从当前工作目录隐式选择本地框架。`--framework-version` 可指定兼容版本。框架版本、依赖更新由项目修改 go.mod，重新生成不会代为升级依赖。
+
+常驻程序、一次性程序用同一份骨架：项目自己的 `Run` 决定何时完成。完整生成项目见 [examples/program](examples/program/README.md)，不需要外部服务。
+
+## 文件职责
+
+| 路径 | 维护方与职责 |
+| --- | --- |
+| `main.go` | 生成器：信号、启动、运行入口监督、退出状态与日志收尾 |
+| `internal/config/loadGen.go` | 生成器：统一配置加载 |
+| `internal/svc/runtimeGen.go` | 生成器：依赖初始化及失败收尾 |
+| `internal/config/config.go` | 项目：Config、Default、Validate；初始只含 log/lifecycle |
+| `internal/config/loader.go` | 项目：按需注册额外文件格式 |
+| `etc/config.yaml` | 项目：配置与显式环境引用 |
+| `internal/svc/serviceContext.go` | 项目：依赖字段、Init、资源与后台工作登记 |
+| `internal/run/run.go` | 项目：Run 的实际实现 |
+| `go.mod`、README、.gitignore、其他 Go 文件 | 项目：生成器不覆盖 |
+| `.goOmni/projectManifest.json` | 生成器：工程身份、模板版本、生成文件哈希；应提交 Git |
+
+配置遵守 [CONFIG.md](CONFIG.md)：默认值 → 文件显式 `${NAME}` / `${NAME:-fallback}` → 类型绑定 → 校验，没有隐式环境覆盖。JSON/YAML/XML 内置；`-config ""` 只用默认值。`-check-config` 不打开日志文件、不初始化依赖、不调用 Run。日志通过独立实例传给 svc，并注入 Context/WorkContext；不替换进程级默认日志实例。
+
+## 运行与退出
+
+```go
+func Run(ctx context.Context, deps *svc.ServiceContext) error {
+    // 一次性程序可完成处理后直接 return nil。
+    // 常驻程序收到 ctx.Done() 后停止自己的主流程。
+    <-ctx.Done()
+    return nil
+}
+```
+
+`nil` 表示正常完成，返回 error 表示运行失败。后台组件用 `RequestShutdown(err)` 报告致命故障，`RequestShutdown(nil)` 请求正常停止。框架不替项目重试、重新调度或重启任务。
+
+依赖在 `svc.Init` 中装配：创建后立即用 `OnClose` 登记清理，后台组件同时登记同名 `OnStop` 和 `OnDrain`。所有登记应在 Init 返回前完成；Run 不得并发追加生命周期登记。组件何时接收工作由项目决定，停止后不得重新开始领取或启动未登记的工作。
+
+- `Context()` 是提前停止通知，用来停止主流程或接收新工作。
+- `WorkContext()` 在正常排空期间仍有效，用于已接受的工作。
+- `OnStop` 停止接收新工作，不关闭处理中的工作仍依赖的资源。
+- `OnDrain` 返回 nil，必须意味着组件处理、确认和 defer 收尾均已结束。仅返回 `ctx.Err()` 不能证明结束。
+- 全部停止钩子先于全部排空钩子；同阶段并行。有先后依赖的组件在一个钩子内显式排序。
+- 全部工作确认结束后，资源按 `OnClose` 登记的反序释放，最后关闭入口拥有的日志。
+
+生成入口自动监督 Run 本身，以 `go-omni/project/run` 保留名称登记完成屏障。收到信号、Run 返回或报告故障后开始收尾，同时等待 Run 及其他已登记工作。Run 不应等待资源关闭：资源关闭发生在 Run 完成之后。
+
+初始化失败同样收尾已创建的资源和已启动的工作。Init/Run 内 panic 被转为失败，安全收尾后进程以非零状态退出；任意自建 goroutine 的 panic 仍由项目负责处理。Run 不响应取消或其他工作无法确认结束时，`lifecycle.stopTimeout/drainTimeout/cancelTimeout` 限定等待窗口，返回 `ErrResourcesRetained`，跳过共享资源和日志关闭，以失败状态退出。取消后的工作不能被 Go 强制终止，保留资源不代表工作已经完成。SIGKILL 和进程崩溃不会执行退出钩子。
+
+详见 [生命周期契约](lifecycle/README.md)。现成组件必须按其真实停止/完成语义适配，不能把某个 `Run/Close` 返回直接视为业务结束。
+
+## 生成检查与兼容
+
+```sh
+go-omni project generate --dry-run
+go-omni project generate
+go-omni project check              # 等价于 project generate --check
+go test ./...
+```
+
+生成器不执行项目 Go 代码、不下载依赖。check/预览只读，不创建锁文件；生成时使用独立项目锁、路径和哈希预检。生成文件被手工修改会报冲突，不提供强制覆盖。删除的生成文件可补回；缺失的项目所有文件必须显式恢复，避免把删除的业务文件当成空白骨架重建。
+
+每个文件通过原子替换写入，普通写入失败回滚此前变更；整个目录不具备崩溃事务性。生成期间不要同时手工编辑。发现遗留 project.lock 时，先确认没有生成进程再手工移除。
+
+check 检查模板漂移和必要文件，不检查业务正确性，也不能替代 Go 编译与测试。新的模板版本会重新生成受管文件；不自动合并项目所有文件或更新 go.mod。未知的新清单版本会要求使用兼容 CLI。
+
+原有 `new` / `api new` 及 API 工程行为保留。通用工程使用自己的清单和命令，不能交给 `api generate` 或 `add` 转换；新增业务包直接写普通 Go。现有 `workspace` 命令仍面向 API 契约工程；多个通用工程可分别执行 `project check --dir <目录>`，本版不引入混合工作区配置。

PROJECT.md

@@ -1,6 +1,8 @@
-# 生成项目与文件维护边界
+# API 生成项目与文件维护边界
 
-v0.27.0-preview 提供受管理的生成项目。安装同版远程 CLI，生成的项目直接引用该版本，无需本地 replace。根目录入口支持 `go run .` 和 `go build .`；框架本身仍然是可直接引用的库。安装和私有仓库访问见 [README](README.md#准备环境与安装)。
+通用 Go 工程使用独立的 `project new/generate/check`，见 [PROGRAM.md](PROGRAM.md)。本文说明 API 契约工程。
+
+v0.28.0-preview 提供受管理的生成项目。安装同版远程 CLI，生成的项目直接引用该版本，无需本地 replace。根目录入口支持 `go run .` 和 `go build .`；框架本身仍然是可直接引用的库。安装和私有仓库访问见 [README](README.md#准备环境与安装)。
 
 ## 创建和日常开发
 
@@ -215,7 +217,7 @@ get /download (DownloadReq)
 
 ## 已有服务接入步骤
 
-每个独立服务生成一个项目，module 名称、上层目录和共享业务包由项目选择。接入时固定 CLI 与框架版本为 v0.27.0-preview：
+每个独立服务生成一个项目，module 名称、上层目录和共享业务包由项目选择。接入时固定 CLI 与框架版本为 v0.28.0-preview：
 
 1. 先保留旧服务，整理实际路由及现有响应、鉴权和超时要求。在新目录执行 `go-omni new --api /path/to/service.api --module example.com/service ./service`；不对旧入口强制覆盖。
 2. 在 `.api` 中选择 `@app(defaultResponse: ...)`，显式保留原项目的字段、成功码、错误码和 `dataMode`。需要独立回执的路由单独声明 raw/produces。普通路由、404/405 和提前返回的中间件一起验收。

README.md

@@ -1,12 +1,14 @@
 # GoOmni
 
-GoOmni 是面向多个业务项目复用的 Go 后端框架：用 `.api` 定义接口、请求和返回类型，生成项目目录、HTTP 接入代码及 OpenAPI，业务代码负责 Logic 和 Repository。也可以在已有项目中直接使用 `omni.New()`，或单独引入日志、存储等模块。
+GoOmni 是面向多个项目复用的 Go 基础框架。通用工程使用 `project new` 生成配置、日志、依赖装配、生命周期和普通 Go 运行入口；需要 HTTP 接口时可选择 `.api` 工程生成，也可以在已有项目中按需引入独立模块。运行方式、业务类型和外部依赖由项目决定。
+
+**v0.28 改动**：新增独立的 `project new/generate/check`，默认无 API、监听端口、业务任务或外部服务配置；保护手写代码，并等待主运行入口和登记的后台工作结束后释放依赖。见 [通用工程指南](PROGRAM.md)和[可运行示例](examples/program/README.md)。
 
 **v0.27 改动**：统一三种内置服务实现的默认/路由/硬请求体限额，配置冲突在启动前报错；停机以处理函数实际退出为资源清理前提，超时仍有请求时保留共享依赖。见 [HTTP 策略](transport/README.md#统一请求体限额)、[停机规则](lifecycle/README.md#http-请求与依赖的关闭屏障)和[可运行示例](examples/httpSafety/README.md)。
 
-**v0.26 改动**：通用 [i18n](i18n/README.md)，提供独立词典、语言匹配、回退、命名参数/条件/复数、可选 HTTP 与错误适配、检查/导出 CLI 及前端运行时。文案由项目维护；[完整示例](examples/i18n/README.md)可直接运行。CLI 与框架使用同版 v0.27.0-preview。同时修复 Go 1.22 下请求体限额错误的识别。
+**v0.26 改动**：通用 [i18n](i18n/README.md)，提供独立词典、语言匹配、回退、命名参数/条件/复数、可选 HTTP 与错误适配、检查/导出 CLI 及前端运行时。文案由项目维护；[完整示例](examples/i18n/README.md)可直接运行。CLI 与框架使用同版 v0.28.0-preview。同时修复 Go 1.22 下请求体限额错误的识别。
 
-**从这份 README 开始接入。** 当前版本 **`v0.27.0-preview`**，新生成项目采用根目录入口和 `config / svc / logic / handler`。可以固定版本开展业务接入；文件维护边界和已有服务迁移步骤见 [项目指南](PROJECT.md)，版本变化与验收见 [发布说明](RELEASE.md)。
+**从这份 README 开始接入。** 当前版本 **`v0.28.0-preview`**，通用工程采用根目录入口和 `config / svc / run`；API 工程使用 `config / svc / logic / handler`。可以固定版本开展业务接入；文件维护边界和已有服务迁移步骤见 [项目指南](PROJECT.md)，版本变化与验收见 [发布说明](RELEASE.md)。
 
 **v0.25 改动**：`database.InTx` 返回可识别的事务阶段与结果，保留业务/驱动及回滚错误链；提交报错保守标记为结果不确定，不等同于已回滚。[使用规则](database/README.md#事务阶段与结果)、[可运行故障示例](examples/transactions/README.md)。
 
@@ -38,6 +40,7 @@ Go **1.22+**。框架不依赖 Gin，默认使用标准库网络层，提供可
 | --- | --- | --- |
 | 项目、接口与文档生成 | `go-omni new`；改 `.api` 后 `api generate`；`--check` 检查漂移 | [下方快速开始](#新项目生成并运行)、[CLI](cmd/go-omni/README.md)、[完整生成项目](examples/managedService/README.md) |
 | 公共字段与跨服务共享契约 | `.api` 组合对象字段；`omni.imports.json` 声明共享根；workspace 批量生成 | [公共字段示例](GENERATION.md#公共字段组合)、[共享契约与 workspace](DEVELOPMENT.md) |
+| 通用 Go 工程 | `go-omni project new/generate/check`；配置、日志、依赖、运行与退出 | [通用工程指南](PROGRAM.md)、[完整可运行示例](examples/program/README.md) |
 | 中间件依赖工厂、可选 Repository | `omni.gen.json` 选择 factories / none；在 `New<Name>(deps)` 写一次实现 | [配置与完整工厂示例](GENERATION.md) |
 | 路由、分组、请求上下文 | `omni.New()`、`app.GET` / `Group` / `Use`；业务使用 `context.Context` | [基本服务](examples/basic/main.go)、[已有项目接入](#已有项目按模块接入) |
 | HTTP 网络与扩展适配 | 配置 transport 为 nethttp / native / http2；自定义 Router/Runner | [网络层配置与契约](transport/README.md)、[性能与限制](PERFORMANCE.md) |
@@ -66,6 +69,22 @@ Go **1.22+**。框架不依赖 Gin，默认使用标准库网络层，提供可
 | 可选结构转换与深拷贝 | `copyx.Copy` / `Clone` / `New`；`Check[S,T]` 预检类型，Go converter 处理差异 | [下方示例](#可选结构转换与深拷贝)、[完整 copyx 指南](COPY.md)、[可运行代码](examples/copying) |
 | 自定义适配器验收 | `transporttest.Run`、`storagetest.Run` / `RunUploads` 验证扩展契约 | [网络契约测试入口](transport/transporttest/router.go)、[存储契约测试入口](storage/storagetest/contract.go) |
 
+## 通用工程快速开始
+
+```sh
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.28.0-preview
+go-omni project new demo --module example.com/demo
+cd demo
+go mod tidy
+go run . -check-config
+go run .
+# Ctrl+C / SIGTERM 退出；项目自己的 Run 也可以完成后直接返回。
+go-omni project check
+go test ./...
+```
+
+项目只修改配置、svc 依赖初始化和 Run；默认没有 HTTP 端口、数据库、队列或自动重试。`main.go`、加载和装配代码由生成器维护；手改受管文件会报冲突，手写文件保持。完整维护边界、异常退出和超时行为见 [PROGRAM.md](PROGRAM.md)。
+
 ## 浏览器跨域 CORS
 
 同源部署保持默认关闭；需要跨域时，在生成项目的配置文件中加入：
@@ -158,7 +177,7 @@ module 地址是 `git.yuntuo.hk/k2safe/go-omni`。先确保本机 Go 和 Git 可
 
 ```sh
 export GOPRIVATE="$(go env GOPRIVATE),git.yuntuo.hk"
-go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.27.0-preview
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.28.0-preview
 export PATH="$(go env GOPATH)/bin:$PATH"
 go-omni --help
 ```
@@ -315,7 +334,7 @@ go-omni new --api catalog.api \
 在业务项目的 **go.mod 所在目录**执行：
 
 ```sh
-go get git.yuntuo.hk/k2safe/go-omni@v0.27.0-preview
+go get git.yuntuo.hk/k2safe/go-omni@v0.28.0-preview
 ```
 
 已有项目可直接复用现有目录、Service、Repository 和数据库连接，先选择一个接口接入。也可以只用 `logx`、`storage` 等包，暂时保留原来的 HTTP 框架。希望入口和 HTTP 接入都交给生成器的项目，按 [已有服务接入步骤](PROJECT.md#已有服务接入步骤) 在新目录生成后迁入业务代码。
@@ -646,7 +665,7 @@ go test ./...
 
 `main.go`、`Gen.go`、`docs/openapi.json` 和 manifest 由生成器管理，手动修改会报告冲突。Logic、Repository、中间件实现、配置和依赖装配属于项目，重复生成保留手写内容。契约变化会提示受影响的 Logic 文件和 DTO 字段，明确的签名错误会给出原签名与期望签名；生成后 `--check` 仍能检出未修复的问题。将 `.api`、`omni.gen.json`、生成文件和 `.goOmni/apiManifest.json` 一起提交，CI 同时运行 `generate --check` 与 `go test ./...`。详见 [契约变更提示与检查边界](PROJECT.md#契约变更提示)。
 
-CLI 与业务 module 固定使用 `v0.27.0-preview`。v0.21 及更早项目先按 [配置迁移](CONFIG.md#v022-迁移旧模式已移除) 整理旧标签、文件与 Load，再升级依赖与 CLI 并重新生成，框架维护的 main/runtimeGen 自动更新；v0.13 及更早项目按 [升级预览](DEVELOPMENT.md#v013-项目升级) 处理，不直接覆盖手写入口或业务文件。使用过旧 mapping 的项目必须先完成 [移除迁移](COPY.md#从旧-mapping-迁移)，旧配置或旧生成文件会阻止生成。升级后执行生成检查与业务回归。版本变化、迁移边界和验收记录见 [发布说明](RELEASE.md)。
+CLI 与业务 module 固定使用 `v0.28.0-preview`。v0.21 及更早项目先按 [配置迁移](CONFIG.md#v022-迁移旧模式已移除) 整理旧标签、文件与 Load，再升级依赖与 CLI 并重新生成，框架维护的 main/runtimeGen 自动更新；v0.13 及更早项目按 [升级预览](DEVELOPMENT.md#v013-项目升级) 处理，不直接覆盖手写入口或业务文件。使用过旧 mapping 的项目必须先完成 [移除迁移](COPY.md#从旧-mapping-迁移)，旧配置或旧生成文件会阻止生成。升级后执行生成检查与业务回归。版本变化、迁移边界和验收记录见 [发布说明](RELEASE.md)。
 
 ## 按需深入
 

RELEASE.md

@@ -1,3 +1,25 @@
+# v0.28.0-preview
+
+新增通用 Go 工程生成命令 `project new/generate/check`。默认只有配置、日志、svc 依赖装配、生命周期与项目维护的 Run 入口，不生成 API、HTTP Handler、Swagger、业务任务或网络监听，也不自动连接数据库/队列或重试任务。常驻和一次性程序由普通 Go 代码决定。
+
+入口监督 Run 的真实完成并复用现有 Runtime：信号、正常结束、运行错误或初始化失败都会进入收尾；先停止接收工作、等待已登记工作及 Run 结束，再反序释放依赖并关闭日志。Run/Init panic 转为失败；超时仍有工作则传播 ErrResourcesRetained，保留共享资源及日志，以非零状态退出。组件登记在 svc.Init 完成，业务语义和调度方式由项目负责。
+
+配置遵守现有显式文件引用约定；支持 -check-config，在初始化日志和依赖前校验。生成器只管理 main/loadGen/runtimeGen，手写文件保留，生成文件被修改时拒绝覆盖；check/预览只读，独立 manifest/锁和共享文件事务保障生成。新模板要求框架 v0.28.0-preview；已有 new/api/workspace 行为保留，无强制迁移和新增第三方依赖。
+
+```sh
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.28.0-preview
+go-omni project new demo --module example.com/demo
+cd demo
+go mod tidy
+go run . -check-config
+go run .
+go-omni project check
+```
+
+完整 [通用工程指南](PROGRAM.md)、[可运行示例](examples/program/README.md)、[回归记录](reports/programAcceptance.md)。56 个测试包全量 race 与 Go 1.22 回归、生成消费者、vet/build 和真实进程退出验证通过。
+
+---
+
 # v0.27.0-preview
 
 新增统一请求体策略与请求完成屏障，无业务字段、数据库依赖或新第三方包。`server.http.defaultMaxBodyBytes` 控制普通路由默认值（零为 8 MiB），`maxBodyBytes` 为不可由路由突破的服务硬上限（零仅保留 1 TiB 框架上界）。已有显式路由和生成契约限额保持，冲突会在启动前报错；旧 nethttp 手写大请求需显式设置路由或默认上限。multipart 单文件、中间件缓存及代理限额仍各自配置。
@@ -15,6 +37,8 @@ go test ./...
 
 54 个测试包全量 race、Go 1.22 兼容检查、生成项目集成测试、vet/build 及真实进程关闭检查通过，见 [验收记录](reports/httpSafetyAcceptance.md)。
 
+空模块缓存安装远程固定版本后，10 组生成消费者和 98 项发布检查通过，耗时 107.57 秒，无本地 replace；覆盖上传限额、取消收尾、HTTP/2 断连、生成项目依赖与日志保留。标签固定在 `3b00bb55d189cbe480c7d15c8d14bcd09d3f2d52`，见 [远程验收记录](reports/httpSafetyRemote.json)。
+
 ---
 
 # v0.26.0-preview

cmd/go-omni/README.md

@@ -1,5 +1,7 @@
 # go-omni CLI
 
+v0.28 新增 `project new/generate/check`：生成无 API、无监听端口和无外部服务依赖的通用 Go 程序，配置/日志/生命周期自动装配，项目维护 svc 与 Run。`project generate --dry-run` 预览，`project check` 只读检查；详见 [通用工程指南](../../PROGRAM.md)。
+
 v0.26 新增 `i18n check|export|types|extract`：检查独立语言资源、提取 Go 静态消息引用或已导出的错误目录，导出指定命名空间的前端包和 TypeScript 类型。输入只读，结果写 stdout；动态引用明确报告。完整命令见 [国际化工具链](../../i18n/README.md#cli-提取检查与导出)。`.api errorCatalog` 可声明 translation 引用，旧 runtime 在生成前拒绝，接入时使用当前同版 CLI 与框架。
 
 v0.19 移除结构映射生成：`omni.gen.json` 只保留 Repository 和中间件选项。普通接口直接使用生成 DTO；需要类型转换时用普通 Go 或可选 [copyx](../../COPY.md)。旧 `mappings` / `mappingFiles` 必须按迁移步骤清理，CLI 不会静默删除仍在调用的旧生成文件。
@@ -10,13 +12,13 @@ v0.16 增加基础类型/动态 JSON 数组返回、OpenAPI 公共引用和 work
 
 v0.14 新增 `api format [--check]`、`api upgrade [--dry-run|--preview <空目录>|--apply]`，以及 `workspace format|generate|check --file omni.workspace.json`。详见 [通用开发指南](../../DEVELOPMENT.md)。
 
-新项目采用根目录 `main.go` 与 `internal/config、svc、logic、handler、types`。完整职责、启动扩展、流式接口和生成文件边界见 [项目指南](../../PROJECT.md)。
+API 新项目采用根目录 `main.go` 与 `internal/config、svc、logic、handler、types`。完整职责、启动扩展、流式接口和生成文件边界见 [项目指南](../../PROJECT.md)。
 
-## 创建项目
+## 创建 API 项目
 
 ```sh
 # 仓库读取权限与 PATH 配置见根目录 README
-go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.27.0-preview
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.28.0-preview
 go-omni new --module example.com/hello ./hello
 
 # 从自己的契约生成；service.api 及其相对 import 文件需要在本地存在
@@ -51,14 +53,14 @@ main、Gen.go、OpenAPI 和 manifest 由生成器维护；业务文件按字节
 
 ## 版本与迁移
 
-CLI 与框架依赖固定使用 v0.27.0-preview。远程安装的 CLI 默认把自身版本写入 go.mod，不添加本地 replace；`--framework-version` 可显式指定已发布的兼容版本。仅在开发框架源码时使用本地替换：
+CLI 与框架依赖固定使用 v0.28.0-preview。远程安装的 CLI 默认把自身版本写入 go.mod，不添加本地 replace；`--framework-version` 可显式指定已发布的兼容版本。仅在开发框架源码时使用本地替换：
 
 ```sh
 # 在 go-omni 源码仓库中执行
 go run ./cmd/go-omni new --module example.com/hello --framework-dir . ../hello
 ```
 
-当前模板与依赖以 v0.27.0-preview 为基线，继续使用 manifest v2；GORM 可选适配器从 v0.14.1-preview 提供。已有项目使用 [定点升级与预览](../../DEVELOPMENT.md#v013-项目升级)：原始模板可自动替换，含业务修改的基础文件按预览合并；通用清理由 Runtime 负责。独立工具命令不会被删除。受管理项目通过 `.api` 模块导入增加业务，不使用旧 `add` 命令的手动路由装配。
+当前模板与依赖以 v0.28.0-preview 为基线，继续使用 manifest v2；GORM 可选适配器从 v0.14.1-preview 提供。已有项目使用 [定点升级与预览](../../DEVELOPMENT.md#v013-项目升级)：原始模板可自动替换，含业务修改的基础文件按预览合并；通用清理由 Runtime 负责。独立工具命令不会被删除。受管理项目通过 `.api` 模块导入增加业务，不使用旧 `add` 命令的手动路由装配。
 
 ## 数据库迁移命令
 

cmd/go-omni/apigen/generate.go

@@ -12,6 +12,7 @@ import (
 	"strconv"
 	"strings"
 
+	"git.yuntuo.hk/k2safe/go-omni/cmd/go-omni/internal/genfs"
 	"git.yuntuo.hk/k2safe/go-omni/cmd/go-omni/scaffold"
 	"golang.org/x/mod/modfile"
 	"golang.org/x/mod/module"
@@ -22,7 +23,7 @@ const frameworkModule = "git.yuntuo.hk/k2safe/go-omni"
 
 // Runtime-only releases need not raise the managed template compatibility floor.
 const minimumVersion = "v0.22.0-preview"
-const currentVersion = "v0.27.0-preview"
+const currentVersion = "v0.28.0-preview"
 const generatedHeader = "// Code generated by go-omni api. DO NOT EDIT.\n"
 
 type Options struct {
@@ -345,25 +346,7 @@ func moduleFile(o Options) ([]byte, error) {
 	}
 	return []byte(text), nil
 }
-func canonical(path string) string {
+func canonical(path string) string { return genfs.Canonical(path) }
-	path, _ = filepath.Abs(path)
-	candidate := path
-	var tail []string
-	for {
-		if resolved, err := filepath.EvalSymlinks(candidate); err == nil {
-			for i := len(tail) - 1; i >= 0; i-- {
-				resolved = filepath.Join(resolved, tail[i])
-			}
-			return resolved
-		}
-		parent := filepath.Dir(candidate)
-		if parent == candidate {
-			return path
-		}
-		tail = append(tail, filepath.Base(candidate))
-		candidate = parent
-	}
-}
 
 func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map[string][]byte, error) {
 	generated, seeds := map[string][]byte{}, map[string][]byte{}

cmd/go-omni/apigen/write.go

@@ -7,6 +7,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"git.yuntuo.hk/k2safe/go-omni/cmd/go-omni/internal/genfs"
 	"os"
 	"path/filepath"
 	"sort"
@@ -244,44 +245,13 @@ func apply(root, module, entry string, generated, seeds map[string][]byte, check
 		}
 		return result, checkErr
 	}
-	// A rollback restores bytes/modes if an ordinary filesystem write fails.
+	transaction := make([]genfs.Change, 0, len(changes))
-	// File replacement is atomic; the whole directory is not crash-atomic.
-	var applied []change
 	for _, c := range changes {
-		if err = safePath(root, c.name); err == nil {
+		transaction = append(transaction, genfs.Change{Name: c.name, Before: c.before, After: c.after, Existed: c.existed, Remove: c.remove, Mode: c.mode})
-			current, e := os.ReadFile(filepath.Join(root, filepath.FromSlash(c.name)))
-			if c.existed {
-				if e != nil || !bytes.Equal(current, c.before) {
-					err = fmt.Errorf("file changed during generation: %s", c.name)
 	}
-			} else if !errors.Is(e, os.ErrNotExist) {
+	return result, genfs.Apply(root, transaction)
-				err = fmt.Errorf("file appeared during generation: %s", c.name)
-			}
-		}
-		if err == nil {
-			if c.remove {
-				err = os.Remove(filepath.Join(root, filepath.FromSlash(c.name)))
-			} else {
-				err = atomicWrite(root, c.name, c.after, c.mode)
-			}
-		}
-		if err != nil {
-			for i := len(applied) - 1; i >= 0; i-- {
-				previous := applied[i]
-				var rollback error
-				if previous.existed {
-					rollback = atomicWrite(root, previous.name, previous.before, previous.mode)
-				} else {
-					rollback = os.Remove(filepath.Join(root, filepath.FromSlash(previous.name)))
-				}
-				err = errors.Join(err, rollback)
-			}
-			return result, err
-		}
-		applied = append(applied, c)
-	}
-	return result, nil
 }
+
 func digest(data []byte) string { sum := sha256.Sum256(data); return hex.EncodeToString(sum[:]) }
 func ownedPath(name string) bool {
 	if name == "internal/config/loadGen.go" {
@@ -298,52 +268,7 @@ func ownedPath(name string) bool {
 	}
 	return strings.HasPrefix(name, "internal/handler/") && strings.HasSuffix(name, "/handlersGen.go")
 }
-func safePath(root, name string) error {
+func safePath(root, name string) error { return genfs.SafePath(root, name) }
-	if filepath.IsAbs(name) || strings.Contains(name, "\\") || filepath.ToSlash(filepath.Clean(name)) != name || name == "." || strings.HasPrefix(name, "../") {
-		return fmt.Errorf("api: unsafe output path %q", name)
-	}
-	path := root
-	parts := strings.Split(name, "/")
-	for i, part := range parts {
-		path = filepath.Join(path, part)
-		info, err := os.Lstat(path)
-		if errors.Is(err, os.ErrNotExist) {
-			continue
-		}
-		if err != nil {
-			return err
-		}
-		if info.Mode()&os.ModeSymlink != 0 {
-			return fmt.Errorf("api: refusing symlink %s", path)
-		}
-		if i < len(parts)-1 && !info.IsDir() {
-			return fmt.Errorf("api: expected directory %s", path)
-		}
-		if i == len(parts)-1 && !info.Mode().IsRegular() {
-			return fmt.Errorf("api: expected regular file %s", path)
-		}
-	}
-	return nil
-}
 func atomicWrite(root, name string, data []byte, mode os.FileMode) error {
-	target := filepath.Join(root, filepath.FromSlash(name))
+	return genfs.AtomicWrite(root, name, data, mode)
-	if err := os.MkdirAll(filepath.Dir(target), 0755); err != nil {
-		return err
-	}
-	f, err := os.CreateTemp(filepath.Dir(target), ".apiGen-*")
-	if err != nil {
-		return err
-	}
-	defer os.Remove(f.Name())
-	if err = f.Chmod(mode); err == nil {
-		_, err = f.Write(data)
-	}
-	if err == nil {
-		err = f.Sync()
-	}
-	err = errors.Join(err, f.Close())
-	if err != nil {
-		return err
-	}
-	return os.Rename(f.Name(), target)
 }

cmd/go-omni/internal/genfs/files.go

@@ -0,0 +1,133 @@
+// Package genfs shares guarded filesystem operations between project generators.
+package genfs
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+func SafePath(root, name string) error {
+	if filepath.IsAbs(name) || strings.Contains(name, "\\") || filepath.ToSlash(filepath.Clean(name)) != name || name == "." || strings.HasPrefix(name, "../") {
+		return fmt.Errorf("generation: unsafe output path %q", name)
+	}
+	path := root
+	parts := strings.Split(name, "/")
+	for i, part := range parts {
+		path = filepath.Join(path, part)
+		info, err := os.Lstat(path)
+		if errors.Is(err, os.ErrNotExist) {
+			continue
+		}
+		if err != nil {
+			return err
+		}
+		if info.Mode()&os.ModeSymlink != 0 {
+			return fmt.Errorf("generation: refusing symlink %s", path)
+		}
+		if i < len(parts)-1 && !info.IsDir() {
+			return fmt.Errorf("generation: expected directory %s", path)
+		}
+		if i == len(parts)-1 && !info.Mode().IsRegular() {
+			return fmt.Errorf("generation: expected regular file %s", path)
+		}
+	}
+	return nil
+}
+func AtomicWrite(root, name string, data []byte, mode os.FileMode) error {
+	target := filepath.Join(root, filepath.FromSlash(name))
+	if err := os.MkdirAll(filepath.Dir(target), 0755); err != nil {
+		return err
+	}
+	f, err := os.CreateTemp(filepath.Dir(target), ".omniGen-*")
+	if err != nil {
+		return err
+	}
+	defer os.Remove(f.Name())
+	if err = f.Chmod(mode); err == nil {
+		_, err = f.Write(data)
+	}
+	if err == nil {
+		err = f.Sync()
+	}
+	err = errors.Join(err, f.Close())
+	if err != nil {
+		return err
+	}
+	return os.Rename(f.Name(), target)
+}
+
+// Change records the preflight snapshot used for conflict detection and rollback.
+type Change struct {
+	Name            string
+	Before, After   []byte
+	Existed, Remove bool
+	Mode            os.FileMode
+}
+
+// Apply replaces individual files atomically and rolls back ordinary write failures.
+// Callers serialize generators with a project lock. This is not crash-atomic across files.
+func Apply(root string, changes []Change) error {
+	var applied []Change
+	for _, c := range changes {
+		err := SafePath(root, c.Name)
+		if err == nil {
+			current, e := os.ReadFile(filepath.Join(root, filepath.FromSlash(c.Name)))
+			if c.Existed {
+				if e != nil || !bytes.Equal(current, c.Before) {
+					err = fmt.Errorf("file changed during generation: %s", c.Name)
+				}
+			} else if !errors.Is(e, os.ErrNotExist) {
+				err = fmt.Errorf("file appeared during generation: %s", c.Name)
+			}
+		}
+		if err == nil {
+			if c.Remove {
+				err = os.Remove(filepath.Join(root, filepath.FromSlash(c.Name)))
+			} else {
+				err = AtomicWrite(root, c.Name, c.After, c.Mode)
+			}
+		}
+		if err != nil {
+			for i := len(applied) - 1; i >= 0; i-- {
+				previous := applied[i]
+				if e := SafePath(root, previous.Name); e != nil {
+					err = errors.Join(err, e)
+					continue
+				}
+				if previous.Existed {
+					err = errors.Join(err, AtomicWrite(root, previous.Name, previous.Before, previous.Mode))
+				} else {
+					err = errors.Join(err, os.Remove(filepath.Join(root, filepath.FromSlash(previous.Name))))
+				}
+			}
+			return err
+		}
+		applied = append(applied, c)
+	}
+	return nil
+}
+
+// Canonical resolves existing parent symlinks even for an output not yet created.
+func Canonical(path string) string {
+	path, _ = filepath.Abs(path)
+	candidate := path
+	var tail []string
+	for {
+		if resolved, err := filepath.EvalSymlinks(candidate); err == nil {
+			for i := len(tail) - 1; i >= 0; i-- {
+				resolved = filepath.Join(resolved, tail[i])
+			}
+			return resolved
+		}
+		parent := filepath.Dir(candidate)
+		if parent == candidate {
+			return path
+		}
+		tail = append(tail, filepath.Base(candidate))
+		candidate = parent
+	}
+}

cmd/go-omni/internal/genfs/files_test.go

@@ -0,0 +1,47 @@
+package genfs
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestConflictRollsBackEarlierWrites(t *testing.T) {
+	root := t.TempDir()
+	if err := os.WriteFile(filepath.Join(root, "one"), []byte("before"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "two"), []byte("concurrent"), 0644); err != nil {
+		t.Fatal(err)
+	}
+	err := Apply(root, []Change{{Name: "one", Before: []byte("before"), After: []byte("after"), Existed: true, Mode: 0600}, {Name: "new", After: []byte("created"), Mode: 0644}, {Name: "two", Before: []byte("stale"), After: []byte("after"), Existed: true, Mode: 0644}})
+	if err == nil {
+		t.Fatal("conflict accepted")
+	}
+	data, _ := os.ReadFile(filepath.Join(root, "one"))
+	info, _ := os.Stat(filepath.Join(root, "one"))
+	if string(data) != "before" || info.Mode().Perm() != 0600 {
+		t.Fatal("rollback did not restore bytes/mode")
+	}
+	if _, err = os.Stat(filepath.Join(root, "new")); !os.IsNotExist(err) {
+		t.Fatal("new output survived rollback")
+	}
+	data, _ = os.ReadFile(filepath.Join(root, "two"))
+	if string(data) != "concurrent" {
+		t.Fatal("concurrent edit overwritten")
+	}
+}
+func TestUnsafePaths(t *testing.T) {
+	root := t.TempDir()
+	for _, name := range []string{"../escape", "a/../../escape", "/outside", "a\\b", ".", "a/../b"} {
+		if SafePath(root, name) == nil {
+			t.Fatal(name)
+		}
+	}
+	if err := os.Symlink(t.TempDir(), filepath.Join(root, "link")); err != nil {
+		t.Fatal(err)
+	}
+	if SafePath(root, "link/file") == nil {
+		t.Fatal("followed symlink")
+	}
+}

cmd/go-omni/main.go

@@ -18,6 +18,11 @@ func main() {
 	}
 
 	switch os.Args[1] {
+	case "project":
+		if err := runProject(os.Args[2:]); err != nil {
+			fmt.Fprintln(os.Stderr, "go-omni project:", err)
+			os.Exit(1)
+		}
 	case "i18n":
 		if err := runI18n(os.Args[2:]); err != nil {
 			fmt.Fprintln(os.Stderr, "go-omni i18n:", err)
@@ -175,6 +180,7 @@ func usage() {
 	fmt.Fprintln(os.Stderr, "GoOmni project tool")
 	fmt.Fprintln(os.Stderr, "")
 	fmt.Fprintln(os.Stderr, "Usage:")
+	fmt.Fprintln(os.Stderr, "  go-omni project <new|generate|check>  Generate a transport-independent Go program")
 	fmt.Fprintln(os.Stderr, "  go-omni i18n <check|export|types|extract>  Validate and export independent language resources")
 	fmt.Fprintln(os.Stderr, "  go-omni migrate [--dir migrations] [--apply] [--dsn-env GO_OMNI_DB_DSN]")
 	fmt.Fprintln(os.Stderr, "  go-omni new [--module <module>] <directory>")
@@ -217,6 +223,9 @@ func runAdd(args []string) error {
 			return fmt.Errorf("unexpected argument %q", arg)
 		}
 	}
+	if _, err := os.Lstat(filepath.Join(directory, ".goOmni", "projectManifest.json")); !errors.Is(err, os.ErrNotExist) {
+		return errors.New("plain Go projects add packages as ordinary Go code; use project generate for infrastructure")
+	}
 	if _, err := os.Stat(filepath.Join(directory, ".goOmni", "apiManifest.json")); err == nil {
 		return errors.New("managed API projects add modules through .api imports and api generate")
 	}

cmd/go-omni/project.go

@@ -0,0 +1,102 @@
+package main
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+
+	"git.yuntuo.hk/k2safe/go-omni/cmd/go-omni/projectgen"
+)
+
+func runProject(args []string) error {
+	if len(args) == 0 || args[0] == "help" || args[0] == "--help" || args[0] == "-h" {
+		projectUsage()
+		return nil
+	}
+	command := args[0]
+	if command != "new" && command != "generate" && command != "check" {
+		return fmt.Errorf("unknown project command %q", command)
+	}
+	o := projectgen.Options{Check: command == "check"}
+	for i := 1; i < len(args); i++ {
+		arg := args[i]
+		if arg == "--help" || arg == "-h" {
+			projectUsage()
+			return nil
+		}
+		if arg == "--check" || arg == "--dry-run" {
+			if command != "generate" {
+				return fmt.Errorf("%s belongs to project generate", arg)
+			}
+			if arg == "--check" {
+				o.Check = true
+			} else {
+				o.DryRun = true
+			}
+			continue
+		}
+		if !strings.HasPrefix(arg, "-") {
+			if command != "new" || o.Dir != "" {
+				return fmt.Errorf("unexpected argument %q", arg)
+			}
+			o.Dir = arg
+			continue
+		}
+		name, value, inline := strings.Cut(arg, "=")
+		switch name {
+		case "--dir", "--module", "--framework-dir", "--framework-version":
+		default:
+			return fmt.Errorf("unknown project option %q", name)
+		}
+		if command != "new" && name != "--dir" {
+			return fmt.Errorf("%s belongs to project new", name)
+		}
+		if !inline {
+			if i+1 >= len(args) || strings.HasPrefix(args[i+1], "-") {
+				return fmt.Errorf("%s requires a value", name)
+			}
+			i++
+			value = args[i]
+		}
+		if strings.TrimSpace(value) == "" {
+			return fmt.Errorf("%s requires a value", name)
+		}
+		switch name {
+		case "--dir":
+			if o.Dir != "" {
+				return errors.New("project directory specified more than once")
+			}
+			o.Dir = value
+		case "--module":
+			o.Module = value
+		case "--framework-dir":
+			o.FrameworkDir = value
+		case "--framework-version":
+			o.FrameworkVersion = value
+		}
+	}
+	var out projectgen.Output
+	var err error
+	if command == "new" {
+		out, err = projectgen.New(o)
+	} else {
+		out, err = projectgen.Generate(o)
+	}
+	if err != nil {
+		return err
+	}
+	if o.DryRun {
+		for _, change := range out.Changes {
+			fmt.Printf("%-7s %s\n", change.Action, change.Path)
+		}
+	} else {
+		fmt.Printf("project %s: %d file changes\n", command, len(out.Changes))
+	}
+	return nil
+}
+func projectUsage() {
+	fmt.Println("go-omni project new <directory> [--module <module>] [--framework-version <version>|--framework-dir <directory>]")
+	fmt.Println("go-omni project generate [--dir <project>] [--check|--dry-run]")
+	fmt.Println("go-omni project check [--dir <project>]")
+	fmt.Println("Creates a plain Go program with config, logging, dependency lifecycle and an editable Run entry.")
+}

cmd/go-omni/project_test.go

@@ -0,0 +1,27 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestProjectCLI(t *testing.T) {
+	root := filepath.Join(t.TempDir(), "program")
+	for _, args := range [][]string{{"new", root, "--module", "example.com/program"}, {"generate", "--dir", root, "--dry-run"}, {"generate", "--dir", root}, {"check", "--dir", root}, {"generate", "--dir", root, "--check"}} {
+		if err := runProject(args); err != nil {
+			t.Fatal(args, err)
+		}
+	}
+	if err := runAdd([]string{"item", "--dir", root}); err == nil {
+		t.Fatal("add adopted plain project")
+	}
+	if _, err := os.Stat(filepath.Join(root, "internal/item")); !os.IsNotExist(err) {
+		t.Fatal("business module generated")
+	}
+	for _, args := range [][]string{{"new"}, {"new", "a", "b"}, {"new", "--api", "x"}, {"check", "--dry-run"}, {"generate", "--check", "--dry-run"}, {"generate", "--module", "x"}, {"new", "--module"}, {"new", "--dir="}, {"new", "--dir", "x", "y"}, {"unknown"}} {
+		if err := runProject(args); err == nil {
+			t.Fatal("accepted", args)
+		}
+	}
+}

cmd/go-omni/projectgen/consumer_test.go

@@ -0,0 +1,190 @@
+package projectgen
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"syscall"
+	"testing"
+	"time"
+)
+
+func TestGeneratedProgramConsumer(t *testing.T) {
+	if os.Getenv("GO_OMNI_SCAFFOLD_INTEGRATION") != "1" {
+		t.Skip("set GO_OMNI_SCAFFOLD_INTEGRATION=1")
+	}
+	root := filepath.Join(t.TempDir(), "program")
+	cli := os.Getenv("GO_OMNI_RELEASE_CLI")
+	if cli != "" {
+		runCommand(t, "", cli, "project", "new", root, "--module", "example.com/plain")
+	} else {
+		framework, err := filepath.Abs("../../..")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if _, err = New(Options{Dir: root, Module: "example.com/plain", FrameworkDir: framework}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	// Only project-owned files are customized. All entry/loading/lifecycle code
+	// remains exactly what the local or downloaded CLI generated.
+	svc := get(t, root, "internal/svc/serviceContext.go")
+	svc = strings.Replace(svc, "return nil", "return Initialize(ctx, c)", 1)
+	svc += "\nvar Initialize = func(context.Context, *ServiceContext) error { return nil }\n"
+	put(t, root, "internal/svc/serviceContext.go", svc)
+	put(t, root, "internal/run/run.go", `package run
+ import("context";"errors";"os";"example.com/plain/internal/svc")
+ var Execute=func(ctx context.Context,deps *svc.ServiceContext)error{
+ switch os.Getenv("GO_OMNI_PROGRAM_TEST_MODE") {case "error":return errors.New("process failure marker");case "panic":panic("process panic marker");case "unresponsive":select{}}
+ <-ctx.Done();return nil
+}
+ func Run(ctx context.Context,deps *svc.ServiceContext)error{return Execute(ctx,deps)}
+ `)
+	put(t, root, "consumer_test.go", get(t, "testdata", "consumer_test.go"))
+	runCommand(t, root, "go", "mod", "tidy")
+	runCommand(t, root, "go", "test", "-race", "-count=1", "./...")
+	runCommand(t, root, "go", "vet", "./...")
+	binary := filepath.Join(root, "program")
+	runCommand(t, root, "go", "build", "-race", "-o", binary, ".")
+	before := snapshot(t, root)
+	for _, mode := range []string{"generate", "check", "dry-run"} {
+		if cli != "" {
+			args := []string{"project", mode, "--dir", root}
+			if mode == "dry-run" {
+				args = []string{"project", "generate", "--dir", root, "--dry-run"}
+			}
+			runCommand(t, root, cli, args...)
+		} else {
+			if _, err := Generate(Options{Dir: root, Check: mode == "check", DryRun: mode == "dry-run"}); err != nil {
+				t.Fatal(err)
+			}
+		}
+	}
+	after := snapshot(t, root)
+	for name, data := range before {
+		if after[name] != data {
+			t.Fatal("consumer changed during regeneration", name)
+		}
+	}
+	// Validation must not open even the configured log file.
+	logfile := filepath.Join(root, "check-must-not-open.log")
+	cfg := filepath.Join(root, "check.json")
+	raw, _ := json.Marshal(map[string]any{"log": map[string]any{"file": logfile}})
+	put(t, root, "check.json", string(raw))
+	runCommand(t, root, binary, "-config", cfg, "-check-config")
+	if _, err := os.Stat(logfile); !os.IsNotExist(err) {
+		t.Fatal("check-config opened logger", err)
+	}
+	put(t, root, "check.json", `{"log":{"level":"invalid"}}`)
+	cmd := exec.Command(binary, "-config", cfg, "-check-config")
+	cmd.Dir = root
+	if data, err := cmd.CombinedOutput(); err == nil || !strings.Contains(string(data), "log.level") {
+		t.Fatal("invalid config accepted", string(data), err)
+	}
+	for _, sig := range []os.Signal{os.Interrupt, syscall.SIGTERM} {
+		testProcess(t, root, binary, sig, "")
+	}
+	for _, mode := range []string{"error", "panic", "unresponsive"} {
+		var sig os.Signal
+		if mode == "unresponsive" {
+			sig = syscall.SIGTERM
+		}
+		testProcess(t, root, binary, sig, mode)
+	}
+	if cli != "" {
+		data := runCommand(t, root, "go", "list", "-m", "-json", frameworkModule)
+		var dep struct {
+			Version, Sum string
+			Replace      any
+		}
+		if err := json.Unmarshal([]byte(data), &dep); err != nil {
+			t.Fatal(err)
+		}
+		if dep.Version != os.Getenv("GO_OMNI_RELEASE_VERSION") || dep.Replace != nil || dep.Sum == "" {
+			t.Fatal("not a fixed remote consumer", dep)
+		}
+		t.Logf("remote framework %s checksum %s; no local replace", dep.Version, dep.Sum)
+	}
+}
+func runCommand(t *testing.T, dir, name string, args ...string) string {
+	t.Helper()
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Minute)
+	defer cancel()
+	cmd := exec.CommandContext(ctx, name, args...)
+	if dir != "" {
+		cmd.Dir = dir
+	}
+	cmd.Env = append(os.Environ(), "GOWORK=off")
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("%s %v: %v\n%s", name, args, err, output)
+	}
+	t.Logf("%s %v\n%s", name, args, output)
+	return string(output)
+}
+func testProcess(t *testing.T, root, binary string, sig os.Signal, mode string) {
+	t.Helper()
+	logfile, err := os.CreateTemp(root, "signal-*.log")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer logfile.Close()
+	cfg := filepath.Join(root, "process.json")
+	put(t, root, "process.json", `{"lifecycle":{"stopTimeout":"100ms","drainTimeout":"30ms","cancelTimeout":"100ms"}}`)
+	cmd := exec.Command(binary, "-config", cfg)
+	cmd.Env = append(os.Environ(), "GO_OMNI_PROGRAM_TEST_MODE="+mode)
+	cmd.Dir = root
+	cmd.Stdout = logfile
+	cmd.Stderr = logfile
+	if err = cmd.Start(); err != nil {
+		t.Fatal(err)
+	}
+	done := make(chan error, 1)
+	go func() { done <- cmd.Wait() }()
+	defer func() { _ = cmd.Process.Kill() }()
+	deadline := time.Now().Add(10 * time.Second)
+	for {
+		data, _ := os.ReadFile(logfile.Name())
+		if strings.Contains(string(data), "program.starting") {
+			break
+		}
+		if time.Now().After(deadline) {
+			t.Fatal("program did not start", string(data))
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	if path, err := exec.LookPath("lsof"); err == nil {
+		output, _ := exec.Command(path, "-nP", "-a", "-p", strconv.Itoa(cmd.Process.Pid), "-i").CombinedOutput()
+		if strings.Contains(string(output), "TCP") || strings.Contains(string(output), "UDP") {
+			t.Fatal("starter opened network socket", string(output))
+		}
+	}
+	if sig != nil {
+		if err = cmd.Process.Signal(sig); err != nil {
+			t.Fatal(err)
+		}
+	}
+	select {
+	case err = <-done:
+		data, _ := os.ReadFile(logfile.Name())
+		if mode == "" && err != nil {
+			t.Fatal("signal exit failed", err, string(data))
+		}
+		if mode != "" {
+			exit, ok := err.(*exec.ExitError)
+			if !ok || exit.ExitCode() != 1 {
+				t.Fatal("abnormal process exit status", err, string(data))
+			}
+		}
+		if mode == "unresponsive" && !strings.Contains(string(data), "shared resources retained") {
+			t.Fatal("timeout did not retain resources", string(data))
+		}
+		t.Logf("process mode=%q signal=%v passed", mode, sig)
+	case <-time.After(10 * time.Second):
+		t.Fatal("signal exit timed out")
+	}
+}

cmd/go-omni/projectgen/generate.go

@@ -0,0 +1,359 @@
+// Package projectgen generates transport-independent Go programs.
+package projectgen
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"embed"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"go/format"
+	"io"
+	"os"
+	"path/filepath"
+	"runtime/debug"
+	"sort"
+	"strconv"
+	"strings"
+
+	"git.yuntuo.hk/k2safe/go-omni/cmd/go-omni/internal/genfs"
+	"golang.org/x/mod/modfile"
+	"golang.org/x/mod/module"
+	"golang.org/x/mod/semver"
+)
+
+const frameworkModule = "git.yuntuo.hk/k2safe/go-omni"
+const currentVersion = "v0.28.0-preview"
+const minimumVersion = "v0.28.0-preview"
+const manifestPath = ".goOmni/projectManifest.json"
+const lockPath = ".goOmni/project.lock"
+const header = "// Code generated by go-omni project. DO NOT EDIT.\n"
+
+//go:embed templates/*
+var templates embed.FS
+
+var managed = map[string]bool{"main.go": true, "internal/config/loadGen.go": true, "internal/svc/runtimeGen.go": true}
+var seeds = []string{"go.mod", ".gitignore", "README.md", "etc/config.yaml", "internal/config/config.go", "internal/config/loader.go", "internal/svc/serviceContext.go", "internal/run/run.go"}
+
+type Options struct {
+	Dir, Module, FrameworkDir, FrameworkVersion string
+	Check, DryRun                               bool
+}
+type FileChange struct{ Path, Action string }
+type Output struct{ Changes []FileChange }
+type manifest struct {
+	Version         int               `json:"version"`
+	Kind            string            `json:"kind"`
+	TemplateVersion string            `json:"templateVersion"`
+	Module          string            `json:"module"`
+	Generated       map[string]string `json:"generated"`
+}
+
+// New only accepts an empty directory. FrameworkDir is an explicit development opt-in.
+func New(o Options) (Output, error) {
+	if o.Dir == "" || o.Check || o.DryRun {
+		return Output{}, errors.New("project new requires a directory and does not accept --check/--dry-run")
+	}
+	if entries, err := os.ReadDir(o.Dir); err == nil && len(entries) > 0 {
+		return Output{}, errors.New("project new requires an empty directory")
+	} else if err != nil && !errors.Is(err, os.ErrNotExist) {
+		return Output{}, err
+	}
+	if o.Module == "" {
+		o.Module = filepath.Base(genfs.Canonical(o.Dir))
+	}
+	if err := module.CheckImportPath(o.Module); err != nil {
+		return Output{}, err
+	}
+	if _, err := moduleFile(o, genfs.Canonical(o.Dir), true); err != nil {
+		return Output{}, err
+	}
+	return generate(o, true)
+}
+func Generate(o Options) (Output, error) { return generate(o, false) }
+
+func generate(o Options, create bool) (out Output, err error) {
+	if o.Check && o.DryRun {
+		return out, errors.New("--check and --dry-run cannot be combined")
+	}
+	if o.Dir == "" {
+		o.Dir = "."
+	}
+	root, err := filepath.Abs(o.Dir)
+	if err != nil {
+		return out, err
+	}
+	if info, e := os.Lstat(root); e == nil {
+		if !info.IsDir() || info.Mode()&os.ModeSymlink != 0 {
+			return out, errors.New("project directory must be a real directory")
+		}
+	} else if !create || !errors.Is(e, os.ErrNotExist) {
+		return out, e
+	}
+	root = genfs.Canonical(root)
+	for _, name := range append(append([]string{}, seeds...), manifestPath, lockPath) {
+		if err = genfs.SafePath(root, name); err != nil {
+			return out, err
+		}
+	}
+	for name := range managed {
+		if err = genfs.SafePath(root, name); err != nil {
+			return out, err
+		}
+	}
+	for _, other := range []string{".goOmni/apiManifest.json", "api/service.api"} {
+		if _, e := os.Lstat(filepath.Join(root, other)); !errors.Is(e, os.ErrNotExist) {
+			return out, errors.New("project generator requires its own project; existing API layout is not adopted")
+		}
+	}
+	if !o.Check && !o.DryRun {
+		if err = os.MkdirAll(filepath.Join(root, ".goOmni"), 0755); err != nil {
+			return out, err
+		}
+		lock, e := os.OpenFile(filepath.Join(root, lockPath), os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0600)
+		if e != nil {
+			return out, fmt.Errorf("acquire project.lock (check for a running generator before removing a stale lock): %w", e)
+		}
+		_, err = fmt.Fprintf(lock, "pid=%d\n", os.Getpid())
+		err = errors.Join(err, lock.Close())
+		defer os.Remove(filepath.Join(root, lockPath))
+		if err != nil {
+			return out, err
+		}
+	}
+	var old manifest
+	oldData, readErr := os.ReadFile(filepath.Join(root, manifestPath))
+	if create {
+		if !errors.Is(readErr, os.ErrNotExist) {
+			return out, errors.New("project manifest appeared during creation")
+		}
+		// Recheck after taking the lock; never adopt files created concurrently.
+		entries, e := os.ReadDir(root)
+		if e != nil {
+			return out, e
+		}
+		for _, entry := range entries {
+			if entry.Name() != ".goOmni" {
+				return out, errors.New("project directory changed during creation")
+			}
+		}
+		entries, e = os.ReadDir(filepath.Join(root, ".goOmni"))
+		if e != nil {
+			return out, e
+		}
+		for _, entry := range entries {
+			if entry.Name() != "project.lock" {
+				return out, errors.New("project metadata appeared during creation")
+			}
+		}
+	} else {
+		if readErr != nil {
+			return out, fmt.Errorf("read project manifest (create with project new first): %w", readErr)
+		}
+		decoder := json.NewDecoder(bytes.NewReader(oldData))
+		decoder.DisallowUnknownFields()
+		if err = decoder.Decode(&old); err != nil {
+			return out, fmt.Errorf("invalid project manifest: %w", err)
+		}
+		var extra any
+		if decoder.Decode(&extra) != io.EOF {
+			return out, errors.New("invalid trailing project manifest data")
+		}
+		if old.Version != 1 || old.Kind != "project" || old.Module == "" || len(old.Generated) != len(managed) || !semver.IsValid(old.TemplateVersion) || semver.Compare(old.TemplateVersion, minimumVersion) > 0 {
+			return out, errors.New("unsupported project manifest; use a compatible CLI")
+		}
+		if o.Module != "" && o.Module != old.Module {
+			return out, errors.New("module differs from project manifest")
+		}
+		o.Module = old.Module
+		for name := range managed {
+			if len(old.Generated[name]) != 64 {
+				return out, fmt.Errorf("invalid manifest ownership for %s", name)
+			}
+		}
+	}
+	if o.Module == "" {
+		o.Module = filepath.Base(root)
+	}
+	if err = module.CheckImportPath(o.Module); err != nil {
+		return out, err
+	}
+	moduleData, err := moduleFile(o, root, create)
+	if err != nil {
+		return out, err
+	}
+	rendered, err := render(o.Module, moduleData)
+	if err != nil {
+		return out, err
+	}
+	next := manifest{Version: 1, Kind: "project", TemplateVersion: minimumVersion, Module: o.Module, Generated: map[string]string{}}
+	var changes []genfs.Change
+	names := make([]string, 0, len(rendered))
+	for name := range rendered {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	for _, name := range names {
+		target := filepath.Join(root, filepath.FromSlash(name))
+		before, e := os.ReadFile(target)
+		exists := e == nil
+		if e != nil && !errors.Is(e, os.ErrNotExist) {
+			return out, e
+		}
+		generated := managed[name]
+		if !generated && !create {
+			if !exists {
+				return out, fmt.Errorf("project-owned file %s is missing; restore it explicitly", name)
+			}
+			continue
+		}
+		if generated {
+			next.Generated[name] = digest(rendered[name])
+			if exists && (create || digest(before) != old.Generated[name]) {
+				return out, fmt.Errorf("generated file %s was edited; move custom code to project-owned files", name)
+			}
+		} else if exists {
+			return out, fmt.Errorf("refusing to adopt %s", name)
+		}
+		if exists && bytes.Equal(before, rendered[name]) {
+			continue
+		}
+		mode := os.FileMode(0644)
+		if exists {
+			info, e := os.Stat(target)
+			if e != nil {
+				return out, e
+			}
+			mode = info.Mode().Perm()
+		}
+		changes = append(changes, genfs.Change{Name: name, Before: before, After: rendered[name], Existed: exists, Mode: mode})
+	}
+	data, err := json.MarshalIndent(next, "", "  ")
+	if err != nil {
+		return out, err
+	}
+	data = append(data, '\n')
+	if !bytes.Equal(oldData, data) {
+		changes = append(changes, genfs.Change{Name: manifestPath, Before: oldData, After: data, Existed: oldData != nil, Mode: 0644})
+	}
+	for _, c := range changes {
+		action := "create"
+		if c.Existed {
+			action = "update"
+		}
+		out.Changes = append(out.Changes, FileChange{c.Name, action})
+	}
+	sort.Slice(out.Changes, func(i, j int) bool { return out.Changes[i].Path < out.Changes[j].Path })
+	if o.DryRun {
+		return out, nil
+	}
+	if o.Check {
+		if len(changes) > 0 {
+			return out, fmt.Errorf("project generation drift: %v", out.Changes)
+		}
+		return out, nil
+	}
+	return out, genfs.Apply(root, changes)
+}
+
+func moduleFile(o Options, root string, create bool) ([]byte, error) {
+	if !create {
+		data, err := os.ReadFile(filepath.Join(root, "go.mod"))
+		if err != nil {
+			return nil, err
+		}
+		mf, err := modfile.Parse("go.mod", data, nil)
+		if err != nil {
+			return nil, err
+		}
+		if mf.Module == nil || mf.Module.Mod.Path != o.Module {
+			return nil, errors.New("go.mod module differs from project manifest")
+		}
+		if o.FrameworkDir != "" || o.FrameworkVersion != "" {
+			return nil, errors.New("framework options belong to project new; update go.mod explicitly")
+		}
+		for _, r := range mf.Require {
+			if r.Mod.Path == frameworkModule && semver.Compare(r.Mod.Version, minimumVersion) >= 0 {
+				return data, nil
+			}
+		}
+		return nil, fmt.Errorf("go.mod must require go-omni %s or newer", minimumVersion)
+	}
+	version := o.FrameworkVersion
+	if version == "" {
+		version = currentVersion
+		if info, ok := debug.ReadBuildInfo(); ok && info.Main.Path == frameworkModule && info.Main.Sum != "" && semver.IsValid(info.Main.Version) {
+			version = info.Main.Version
+		}
+	}
+	if !semver.IsValid(version) || semver.Major(version) != "v0" && semver.Major(version) != "v1" || semver.Compare(version, minimumVersion) < 0 {
+		return nil, fmt.Errorf("framework version must be %s or newer", minimumVersion)
+	}
+	mf := new(modfile.File)
+	if err := mf.AddModuleStmt(o.Module); err != nil {
+		return nil, err
+	}
+	if err := mf.AddGoStmt("1.22.0"); err != nil {
+		return nil, err
+	}
+	if err := mf.AddRequire(frameworkModule, version); err != nil {
+		return nil, err
+	}
+	if o.FrameworkDir != "" {
+		local, err := filepath.Abs(o.FrameworkDir)
+		if err != nil {
+			return nil, err
+		}
+		data, err := os.ReadFile(filepath.Join(local, "go.mod"))
+		if err != nil {
+			return nil, err
+		}
+		source, err := modfile.Parse("go.mod", data, nil)
+		if err != nil || source.Module == nil || source.Module.Mod.Path != frameworkModule {
+			return nil, errors.New("--framework-dir must contain go-omni")
+		}
+		local = genfs.Canonical(local)
+		rel, err := filepath.Rel(root, local)
+		if err != nil {
+			return nil, err
+		}
+		rel = filepath.ToSlash(rel)
+		if !strings.HasPrefix(rel, ".") {
+			rel = "./" + rel
+		}
+		if err = mf.AddReplace(frameworkModule, "", rel, ""); err != nil {
+			return nil, err
+		}
+	}
+	return mf.Format()
+}
+func render(moduleName string, moduleData []byte) (map[string][]byte, error) {
+	files := map[string][]byte{"go.mod": moduleData}
+	paths := append([]string{}, seeds[1:]...)
+	for name := range managed {
+		paths = append(paths, name)
+	}
+	for _, name := range paths {
+		raw, err := templates.ReadFile("templates/" + strings.ReplaceAll(name, "/", "_") + ".tmpl")
+		if err != nil {
+			return nil, err
+		}
+		s := strings.ReplaceAll(string(raw), "\"PROJECT_MODULE\"", strconv.Quote(moduleName))
+		s = strings.ReplaceAll(s, "PROJECT_MODULE/", moduleName+"/")
+		if managed[name] {
+			s = header + s
+		}
+		data := []byte(s)
+		if strings.HasSuffix(name, ".go") {
+			data, err = format.Source(data)
+			if err != nil {
+				return nil, fmt.Errorf("format %s: %w", name, err)
+			}
+		}
+		files[name] = data
+	}
+	return files, nil
+}
+func digest(data []byte) string { sum := sha256.Sum256(data); return hex.EncodeToString(sum[:]) }

cmd/go-omni/projectgen/generate_test.go

@@ -0,0 +1,215 @@
+package projectgen
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func put(t *testing.T, root, name, content string) {
+	t.Helper()
+	p := filepath.Join(root, name)
+	if err := os.MkdirAll(filepath.Dir(p), 0755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(p, []byte(content), 0644); err != nil {
+		t.Fatal(err)
+	}
+}
+func get(t *testing.T, root, name string) string {
+	t.Helper()
+	data, err := os.ReadFile(filepath.Join(root, name))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return string(data)
+}
+func snapshot(t *testing.T, root string) map[string]string {
+	t.Helper()
+	files := map[string]string{}
+	err := filepath.WalkDir(root, func(path string, d os.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if !d.IsDir() {
+			data, e := os.ReadFile(path)
+			if e != nil {
+				return e
+			}
+			rel, _ := filepath.Rel(root, path)
+			files[rel] = string(data)
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return files
+}
+func fresh(t *testing.T) string {
+	t.Helper()
+	root := filepath.Join(t.TempDir(), "program")
+	if _, err := New(Options{Dir: root, Module: "example.com/program"}); err != nil {
+		t.Fatal(err)
+	}
+	return root
+}
+
+func TestOwnershipAndDrift(t *testing.T) {
+	root := fresh(t)
+	files := snapshot(t, root)
+	for name, source := range files {
+		if strings.HasSuffix(name, ".api") || strings.Contains(name, "handler") || strings.Contains(name, "openapi") {
+			t.Fatal("unexpected API output", name)
+		}
+		if strings.HasSuffix(name, ".go") {
+			for _, forbidden := range []string{"net/http", "httpx", "middleware", "ListenAndServe", "database/", "queue/", "task.New"} {
+				if strings.Contains(source, forbidden) {
+					t.Fatal(name, forbidden)
+				}
+			}
+		}
+	}
+	if strings.Contains(files["go.mod"], "replace") || !strings.Contains(files["go.mod"], currentVersion) {
+		t.Fatal("default dependency must be remote and fixed")
+	}
+	for _, name := range seeds {
+		if name != "go.mod" {
+			put(t, root, name, get(t, root, name)+"\n// project edit\n")
+		}
+	}
+	before := snapshot(t, root)
+	for _, o := range []Options{{Dir: root}, {Dir: root, Check: true}, {Dir: root, DryRun: true}} {
+		out, err := Generate(o)
+		if err != nil || len(out.Changes) != 0 {
+			t.Fatal(out, err)
+		}
+	}
+	if !reflect.DeepEqual(before, snapshot(t, root)) {
+		t.Fatal("project files changed")
+	}
+	original := get(t, root, "main.go")
+	put(t, root, "main.go", original+"\n// manual edit\n")
+	for _, o := range []Options{{Dir: root}, {Dir: root, Check: true}, {Dir: root, DryRun: true}} {
+		if _, err := Generate(o); err == nil || !strings.Contains(err.Error(), "was edited") {
+			t.Fatal(err)
+		}
+	}
+	put(t, root, "main.go", original)
+	if err := os.Remove(filepath.Join(root, "main.go")); err != nil {
+		t.Fatal(err)
+	}
+	before = snapshot(t, root)
+	if _, err := Generate(Options{Dir: root, Check: true}); err == nil {
+		t.Fatal("missing output accepted")
+	}
+	if !reflect.DeepEqual(before, snapshot(t, root)) {
+		t.Fatal("check wrote files")
+	}
+	out, err := Generate(Options{Dir: root, DryRun: true})
+	if err != nil || len(out.Changes) != 1 {
+		t.Fatal(out, err)
+	}
+	if !reflect.DeepEqual(before, snapshot(t, root)) {
+		t.Fatal("dry-run wrote files")
+	}
+	if _, err = Generate(Options{Dir: root}); err != nil {
+		t.Fatal(err)
+	}
+	if get(t, root, "main.go") != original {
+		t.Fatal("missing output not restored")
+	}
+	if err = os.Remove(filepath.Join(root, "internal/run/run.go")); err != nil {
+		t.Fatal(err)
+	}
+	if _, err = Generate(Options{Dir: root}); err == nil || !strings.Contains(err.Error(), "project-owned") {
+		t.Fatal("silently recreated handwritten file", err)
+	}
+}
+
+func TestRecordedTemplateUpgrade(t *testing.T) {
+	root := fresh(t)
+	var m manifest
+	if err := json.Unmarshal([]byte(get(t, root, manifestPath)), &m); err != nil {
+		t.Fatal(err)
+	}
+	original := get(t, root, "main.go")
+	older := original + "\n// previous generator baseline\n"
+	put(t, root, "main.go", older)
+	m.Generated["main.go"] = digest([]byte(older))
+	data, _ := json.Marshal(m)
+	put(t, root, manifestPath, string(data))
+	before := snapshot(t, root)
+	if _, err := Generate(Options{Dir: root, Check: true}); err == nil {
+		t.Fatal("stale baseline accepted")
+	}
+	if !reflect.DeepEqual(before, snapshot(t, root)) {
+		t.Fatal("check mutated baseline")
+	}
+	if _, err := Generate(Options{Dir: root}); err != nil {
+		t.Fatal(err)
+	}
+	if get(t, root, "main.go") != original {
+		t.Fatal("template was not updated")
+	}
+}
+func TestProjectGuards(t *testing.T) {
+	for _, tc := range []struct {
+		name, needle string
+		mutate       func(*testing.T, string)
+	}{
+		{"module", "module differs", func(t *testing.T, r string) {
+			put(t, r, "go.mod", strings.Replace(get(t, r, "go.mod"), "example.com/program", "example.com/other", 1))
+		}},
+		{"oldFramework", "must require", func(t *testing.T, r string) {
+			put(t, r, "go.mod", strings.ReplaceAll(get(t, r, "go.mod"), currentVersion, "v0.22.0-preview"))
+		}},
+		{"manifest", "unsupported", func(t *testing.T, r string) { put(t, r, manifestPath, `{"version":1,"kind":"api"}`) }},
+		{"lock", "project.lock", func(t *testing.T, r string) { put(t, r, lockPath, "occupied") }},
+		{"otherGenerator", "existing API", func(t *testing.T, r string) { put(t, r, ".goOmni/apiManifest.json", "{}") }},
+		{"symlink", "symlink", func(t *testing.T, r string) {
+			if e := os.Remove(filepath.Join(r, "main.go")); e != nil {
+				t.Fatal(e)
+			}
+			target := filepath.Join(t.TempDir(), "outside.go")
+			put(t, filepath.Dir(target), "outside.go", "outside")
+			if e := os.Symlink(target, filepath.Join(r, "main.go")); e != nil {
+				t.Fatal(e)
+			}
+		}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			root := fresh(t)
+			tc.mutate(t, root)
+			before := snapshot(t, root)
+			if _, err := Generate(Options{Dir: root}); err == nil || !strings.Contains(err.Error(), tc.needle) {
+				t.Fatal(err)
+			}
+			if !reflect.DeepEqual(before, snapshot(t, root)) {
+				t.Fatal("failed generation changed files")
+			}
+		})
+	}
+	root := fresh(t)
+	before := snapshot(t, root)
+	if _, err := New(Options{Dir: root}); err == nil {
+		t.Fatal("new overwrote project")
+	}
+	if !reflect.DeepEqual(before, snapshot(t, root)) {
+		t.Fatal("new mutated project")
+	}
+	if _, err := Generate(Options{Dir: t.TempDir(), Check: true}); err == nil {
+		t.Fatal("adopted unmanaged directory")
+	}
+	for _, version := range []string{"v0.27.0-preview", "latest", "v2.0.0", "v0.28.0-preview\nreplace bad"} {
+		if _, err := New(Options{Dir: filepath.Join(t.TempDir(), "app"), FrameworkVersion: version}); err == nil {
+			t.Fatal("invalid version", version)
+		}
+	}
+	if _, err := New(Options{Dir: filepath.Join(t.TempDir(), "app"), Module: "example.com/a\nreplace bad"}); err == nil {
+		t.Fatal("invalid module")
+	}
+}

cmd/go-omni/projectgen/templates/.gitignore.tmpl

@@ -0,0 +1,6 @@
+/program
+/var/
+.env
+.env.*
+!.env.example
+/.goOmni/project.lock

cmd/go-omni/projectgen/templates/README.md.tmpl

@@ -0,0 +1,55 @@
+# Go program
+
+This project has no HTTP listener, routes, tasks or external dependencies configured.
+
+```sh
+go mod tidy
+go run . -check-config
+go run .
+# SIGINT/SIGTERM stops the program.
+go build -o program .
+go-omni project generate --dry-run
+go-omni project generate
+go-omni project check
+go test ./...
+```
+
+Use the same fixed CLI and framework version. Local --framework-dir is only for
+explicit source development; normal creation pins the installed CLI version.
+
+Edit internal/config/config.go (Config/Default/Validate), etc/config.yaml and
+internal/config/loader.go for optional decoders. JSON/YAML/XML resolve only
+explicit ${NAME} / ${NAME:-fallback}; fixed values are never implicitly overridden.
+-check-config validates without opening the logger or dependencies.
+
+Add dependencies in internal/svc/serviceContext.go, registering OnClose immediately.
+Register all OnStop/OnDrain hooks in Init, before starting work. Paired hooks use the
+same name. OnStop stops acquisition; OnDrain returns nil only after all processing,
+acknowledgements and defers finish. Runtime executes stop, then drain, then resource
+cleanup in reverse registration order. Callbacks within a phase run concurrently;
+combine components with ordering requirements in a single hook. Accepted work uses
+WorkContext; Context is the early stop notification. No automatic retry or restart
+policy is installed. Adapt external components according to their actual semantics.
+
+Write program behavior in internal/run/run.go. Return nil when a one-shot run finishes;
+return an error for fatal failure. The default Run waits for shutdown. Components may
+call RequestShutdown(err) to report fatal failure. Signal or Run completion starts
+shutdown; the entry waits for Run itself and registered background work. Do not make
+Run wait for resource cleanup: cleanup follows Run completion. Do not register hooks
+concurrently from Run. The drain name go-omni/project/run is reserved.
+
+Run/Init panics are converted to startup/run failures and registered resources are
+cleaned safely. Panics in arbitrary project goroutines must be handled by the project.
+Unresponsive work is bounded by lifecycle timeouts: unfinished work causes
+ErrResourcesRetained, skips shared resource/logger cleanup and exits unsuccessfully.
+Go cannot forcibly stop a goroutine. SIGKILL/process crashes cannot run cleanup.
+
+main.go, internal/config/loadGen.go and internal/svc/runtimeGen.go are generator-owned.
+Manual edits cause a conflict. Other starter files are project-owned and preserved;
+missing project-owned files require explicit restoration. Check is read-only and
+reports missing or stale generated files. It does not compile or execute project code.
+Commit .goOmni/projectManifest.json with the project. Generation uses a project lock,
+preflight checks and per-file atomic replacement with rollback for ordinary write errors;
+it is not crash-atomic across files. Avoid editing files during generation.
+
+Full guide: https://git.yuntuo.hk/k2safe/go-omni/src/branch/main/PROGRAM.md

cmd/go-omni/projectgen/templates/etc_config.yaml.tmpl

@@ -0,0 +1,9 @@
+# Project-owned. Environment references are explicit: ${NAME} or ${NAME:-fallback}.
+log:
+  level: info
+  format: json
+  output: stderr
+lifecycle:
+  stopTimeout: 5s
+  drainTimeout: 10s
+  cancelTimeout: 5s

cmd/go-omni/projectgen/templates/internal_config_config.go.tmpl

@@ -0,0 +1,22 @@
+package config
+
+import (
+ omniConfig "git.yuntuo.hk/k2safe/go-omni/config"
+ "git.yuntuo.hk/k2safe/go-omni/lifecycle"
+ "git.yuntuo.hk/k2safe/go-omni/logx"
+)
+
+// Config, Default and Validate are project-owned. Add project settings here.
+type Config struct {
+ Log logx.Config `json:"log"`
+ Lifecycle lifecycle.ShutdownConfig `json:"lifecycle"`
+}
+func Default() Config {
+ log:=logx.Default();log.Service="PROJECT_MODULE"
+ return Config{Log:log,Lifecycle:lifecycle.DefaultShutdownConfig()}
+}
+func(c Config)Validate()error {
+ if err:=c.Log.Validate();err!=nil{return omniConfig.AtField("log",err)}
+ if err:=c.Lifecycle.Validate();err!=nil{return omniConfig.AtField("lifecycle",err)}
+ return nil
+}

cmd/go-omni/projectgen/templates/internal_config_loadGen.go.tmpl

@@ -0,0 +1,6 @@
+package config
+import omniConfig "git.yuntuo.hk/k2safe/go-omni/config"
+func Load(path string)(Config,error){
+ loader,err:=NewLoader();if err!=nil{return Config{},err}
+ return omniConfig.LoadProject(path,Default(),loader)
+}

cmd/go-omni/projectgen/templates/internal_config_loader.go.tmpl

@@ -0,0 +1,4 @@
+package config
+import omniConfig "git.yuntuo.hk/k2safe/go-omni/config"
+// NewLoader is project-owned. Register additional decoders here if needed.
+func NewLoader()(*omniConfig.Loader,error){return omniConfig.NewLoader()}

cmd/go-omni/projectgen/templates/internal_run_run.go.tmpl

@@ -0,0 +1,13 @@
+package run
+import (
+ "context"
+ "PROJECT_MODULE/internal/svc"
+)
+// Run is project-owned. Return nil for normal completion, or an error to fail.
+// The starter waits for shutdown; a one-shot program can simply return when done.
+// Register background stop/drain hooks in svc.Init, not concurrently here.
+// Accepted background work uses deps.WorkContext(), not the early-stop ctx.
+func Run(ctx context.Context,deps *svc.ServiceContext)error {
+ <-ctx.Done()
+ return nil
+}

cmd/go-omni/projectgen/templates/internal_svc_runtimeGen.go.tmpl

@@ -0,0 +1,23 @@
+package svc
+import (
+ "context"
+ "errors"
+ "fmt"
+ "git.yuntuo.hk/k2safe/go-omni/lifecycle"
+ "git.yuntuo.hk/k2safe/go-omni/logx"
+ "PROJECT_MODULE/internal/config"
+)
+func New(ctx context.Context,logger *logx.Logger,cfg config.Config)(result *ServiceContext,err error){
+ if ctx==nil{ctx=context.Background()}
+ if err=ctx.Err();err!=nil{return nil,errors.Join(err,lifecycle.Cause(ctx))}
+ if logger==nil{return nil,errors.New("service context requires a logger")}
+ if err=cfg.Validate();err!=nil{return nil,err}
+ runtime,err:=lifecycle.NewRuntimeWithConfig(logx.WithLogger(ctx,logger),cfg.Lifecycle);if err!=nil{return nil,err}
+ c:=&ServiceContext{Runtime:runtime,Config:cfg,Logger:logger}
+ defer func(){
+  if p:=recover();p!=nil{err=fmt.Errorf("dependency initialization panic: %v",p)}
+  if err!=nil{result=nil;err=c.Finish(err)}
+ }()
+ if err=c.Init(c.Context());err!=nil{return nil,err}
+ return c,nil
+}

cmd/go-omni/projectgen/templates/internal_svc_serviceContext.go.tmpl

@@ -0,0 +1,21 @@
+package svc
+import (
+ "context"
+ "git.yuntuo.hk/k2safe/go-omni/lifecycle"
+ "git.yuntuo.hk/k2safe/go-omni/logx"
+ "PROJECT_MODULE/internal/config"
+)
+// ServiceContext is project-owned. Add dependencies without global variables.
+// Runtime owns registered resources; Logger is borrowed from the entry point.
+type ServiceContext struct {
+ *lifecycle.Runtime
+ Config config.Config
+ Logger *logx.Logger
+}
+// Init runs before Run. Register resources immediately with OnClose.
+// Register paired OnStop/OnDrain hooks before exposing background work.
+// Use WorkContext for accepted work; Context is the early stop notification.
+// OnDrain returns nil only after processing and final cleanup have completed.
+// Complete all registrations here, before Run can race with shutdown.
+// The drain name "go-omni/project/run" is reserved for the generated entry.
+func(c *ServiceContext)Init(ctx context.Context)error{return nil}

cmd/go-omni/projectgen/templates/main.go.tmpl

@@ -0,0 +1,60 @@
+package main
+
+import (
+ "context"
+ "errors"
+ "flag"
+ "fmt"
+ "log"
+ "os"
+ "os/signal"
+ "syscall"
+ "git.yuntuo.hk/k2safe/go-omni/lifecycle"
+ "git.yuntuo.hk/k2safe/go-omni/logx"
+ "PROJECT_MODULE/internal/config"
+ program "PROJECT_MODULE/internal/run"
+ "PROJECT_MODULE/internal/svc"
+)
+
+func main() {
+ path:=flag.String("config","etc/config.yaml","configuration file; empty uses Default()")
+ check:=flag.Bool("check-config",false,"validate configuration without initializing dependencies")
+ flag.Parse()
+ if *check {if _,err:=config.Load(*path);err!=nil{log.Fatal(err)};return}
+ ctx,stop:=signal.NotifyContext(context.Background(),os.Interrupt,syscall.SIGTERM)
+ defer stop()
+ if err:=run(ctx,*path);err!=nil{log.Fatal(err)}
+}
+
+func run(ctx context.Context,path string)(runErr error) {
+ cfg,err:=config.Load(path);if err!=nil{return err}
+ logger,err:=logx.New(cfg.Log);if err!=nil{return err}
+ var deps *svc.ServiceContext
+ defer func(){
+  if p:=recover();p!=nil{runErr=fmt.Errorf("program initialization panic: %v",p)}
+  if deps!=nil{runErr=deps.Finish(runErr)}
+  // Unjoined work may still use its dependencies and logger. The process exits
+  // unsuccessfully; resource retention never means the work completed.
+  if !errors.Is(runErr,lifecycle.ErrResourcesRetained){runErr=errors.Join(runErr,logger.Close())}
+ }()
+ deps,err=svc.New(ctx,logger,cfg);if err!=nil{return err}
+ if deps.Context().Err()!=nil{return nil}
+ done:=make(chan struct{})
+ // This reserved drain proves Run has actually returned, including its defers.
+ // Runtime bounds the wait even when Run ignores cancellation.
+ deps.OnDrain("go-omni/project/run",func(context.Context)error{<-done;return nil})
+ logger.InfoContext(deps.Context(),"program.starting")
+ go func(){
+  var result error
+  returned:=false
+  defer func(){
+   if p:=recover();p!=nil{result=fmt.Errorf("program run panic: %v",p)} else if !returned{result=errors.New("program run exited without returning")}
+   deps.RequestShutdown(result)
+   close(done)
+  }()
+  result=program.Run(deps.Context(),deps)
+  returned=true
+ }()
+ <-deps.Context().Done()
+ return nil
+}

cmd/go-omni/projectgen/testdata/consumer_test.go

@@ -0,0 +1,283 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"reflect"
+	"runtime"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"example.com/plain/internal/config"
+	program "example.com/plain/internal/run"
+	"example.com/plain/internal/svc"
+	"git.yuntuo.hk/k2safe/go-omni/lifecycle"
+)
+
+func setup(t *testing.T) {
+	t.Helper()
+	svc.Initialize = func(context.Context, *svc.ServiceContext) error { return nil }
+	program.Execute = func(context.Context, *svc.ServiceContext) error { return nil }
+	t.Cleanup(func() {
+		svc.Initialize = func(context.Context, *svc.ServiceContext) error { return nil }
+		program.Execute = func(context.Context, *svc.ServiceContext) error { return nil }
+	})
+}
+func shortConfig(t *testing.T, logfile string) string {
+	t.Helper()
+	p := filepath.Join(t.TempDir(), "config.yaml")
+	text := "log:\n  output: discard\nlifecycle:\n  stopTimeout: 100ms\n  drainTimeout: 30ms\n  cancelTimeout: 100ms\n"
+	if logfile != "" {
+		text = "log:\n  file: " + logfile + "\nlifecycle:\n  stopTimeout: 100ms\n  drainTimeout: 30ms\n  cancelTimeout: 100ms\n"
+	}
+	if err := os.WriteFile(p, []byte(text), 0600); err != nil {
+		t.Fatal(err)
+	}
+	return p
+}
+
+func TestFiniteRunAndCleanupOrder(t *testing.T) {
+	setup(t)
+	var events []string
+	svc.Initialize = func(ctx context.Context, c *svc.ServiceContext) error {
+		events = append(events, "init")
+		c.OnClose(func() error { events = append(events, "first"); return nil })
+		c.OnClose(func() error { events = append(events, "second"); return nil })
+		return nil
+	}
+	program.Execute = func(context.Context, *svc.ServiceContext) error {
+		defer func() { events = append(events, "run defer") }()
+		events = append(events, "run")
+		return nil
+	}
+	if err := run(context.Background(), ""); err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(events, []string{"init", "run", "run defer", "second", "first"}) {
+		t.Fatal(events)
+	}
+}
+func TestInitializationAndRunFailures(t *testing.T) {
+	for _, stage := range []string{"init error", "init panic", "run error", "run panic", "run goexit", "component failure"} {
+		t.Run(stage, func(t *testing.T) {
+			setup(t)
+			boom := errors.New("failure marker")
+			var closed atomic.Int32
+			var started atomic.Bool
+			svc.Initialize = func(ctx context.Context, c *svc.ServiceContext) error {
+				c.OnClose(func() error { closed.Add(1); return nil })
+				if stage == "init error" {
+					return boom
+				}
+				if stage == "init panic" {
+					panic(boom)
+				}
+				return nil
+			}
+			program.Execute = func(ctx context.Context, c *svc.ServiceContext) error {
+				started.Store(true)
+				switch stage {
+				case "run error":
+					return boom
+				case "run panic":
+					panic(boom)
+				case "run goexit":
+					runtime.Goexit()
+				case "component failure":
+					c.RequestShutdown(boom)
+					<-ctx.Done()
+				}
+				return nil
+			}
+			err := run(context.Background(), "")
+			if err == nil || closed.Load() != 1 {
+				t.Fatal(stage, err, closed.Load())
+			}
+			if strings.HasPrefix(stage, "init") && started.Load() {
+				t.Fatal("run started after failed initialization")
+			}
+			if strings.Contains(stage, "error") || stage == "component failure" {
+				if !errors.Is(err, boom) {
+					t.Fatal("failure cause lost", err)
+				}
+			}
+		})
+	}
+}
+func TestGracefulStopDrainsAcknowledgementBeforeClose(t *testing.T) {
+	setup(t)
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	ready := make(chan struct{})
+	stop := make(chan struct{})
+	done := make(chan struct{})
+	var closed, acked atomic.Bool
+	var canceledEarly atomic.Bool
+	svc.Initialize = func(ctx context.Context, c *svc.ServiceContext) error {
+		c.OnClose(func() error {
+			if !acked.Load() {
+				return errors.New("closed before acknowledgement")
+			}
+			closed.Store(true)
+			return nil
+		})
+		c.OnStop("component", func(context.Context) error { close(stop); return nil })
+		c.OnDrain("component", func(context.Context) error { <-done; return nil })
+		go func() {
+			defer close(done)
+			<-stop
+			if c.WorkContext().Err() != nil {
+				canceledEarly.Store(true)
+			}
+			time.Sleep(20 * time.Millisecond)
+			acked.Store(true)
+		}()
+		return nil
+	}
+	program.Execute = func(ctx context.Context, c *svc.ServiceContext) error { close(ready); <-ctx.Done(); return nil }
+	result := make(chan error, 1)
+	go func() { result <- run(ctx, "") }()
+	<-ready
+	cancel()
+	if err := <-result; err != nil || !closed.Load() || canceledEarly.Load() {
+		t.Fatal(err, closed.Load(), canceledEarly.Load())
+	}
+}
+func TestInitializationFailureDrainsStartedWork(t *testing.T) {
+	setup(t)
+	done := make(chan struct{})
+	stop := make(chan struct{})
+	var closed atomic.Bool
+	svc.Initialize = func(ctx context.Context, c *svc.ServiceContext) error {
+		c.OnClose(func() error {
+			select {
+			case <-done:
+				closed.Store(true)
+				return nil
+			default:
+				return errors.New("resource closed while starting work still active")
+			}
+		})
+		c.OnStop("partial", func(context.Context) error { close(stop); return nil })
+		c.OnDrain("partial", func(context.Context) error { <-done; return nil })
+		go func() { defer close(done); <-stop; time.Sleep(10 * time.Millisecond) }()
+		return errors.New("later dependency failed")
+	}
+	if err := run(context.Background(), ""); err == nil || !closed.Load() {
+		t.Fatal(err, closed.Load())
+	}
+}
+func TestCancellationGraceJoinsWork(t *testing.T) {
+	setup(t)
+	done := make(chan struct{})
+	var closed atomic.Bool
+	svc.Initialize = func(ctx context.Context, c *svc.ServiceContext) error {
+		c.OnClose(func() error { closed.Store(true); return nil })
+		c.OnStop("cooperative", func(context.Context) error { return nil })
+		c.OnDrain("cooperative", func(context.Context) error { <-done; return nil })
+		go func() { <-c.WorkContext().Done(); close(done) }()
+		return nil
+	}
+	err := run(context.Background(), shortConfig(t, ""))
+	if !errors.Is(err, context.DeadlineExceeded) || errors.Is(err, lifecycle.ErrResourcesRetained) || !closed.Load() {
+		t.Fatal(err, closed.Load())
+	}
+}
+func TestUnjoinedWorkRetainsDependenciesAndLogger(t *testing.T) {
+	for _, which := range []string{"run", "background", "init failure"} {
+		t.Run(which, func(t *testing.T) {
+			setup(t)
+			ctx, cancel := context.WithCancel(context.Background())
+			defer cancel()
+			release := make(chan struct{})
+			joined := make(chan struct{})
+			ready := make(chan struct{})
+			var closed atomic.Bool
+			var held *svc.ServiceContext
+			logfile := filepath.Join(t.TempDir(), "retained.log")
+			svc.Initialize = func(ctx context.Context, c *svc.ServiceContext) error {
+				held = c
+				c.OnClose(func() error { closed.Store(true); return nil })
+				if which != "run" {
+					c.OnStop("stuck", func(context.Context) error { return nil })
+					c.OnDrain("stuck", func(context.Context) error { <-joined; return nil })
+					go func() { defer close(joined); <-release; c.Logger.Info("after shutdown deadline") }()
+				}
+				if which == "init failure" {
+					return errors.New("initialization failed")
+				}
+				return nil
+			}
+			program.Execute = func(ctx context.Context, c *svc.ServiceContext) error {
+				close(ready)
+				if which == "run" {
+					defer close(joined)
+					<-release
+					c.Logger.Info("after shutdown deadline")
+				} else {
+					<-ctx.Done()
+				}
+				return nil
+			}
+			result := make(chan error, 1)
+			go func() { result <- run(ctx, shortConfig(t, logfile)) }()
+			if which != "init failure" {
+				<-ready
+				cancel()
+			}
+			var err error
+			select {
+			case err = <-result:
+			case <-time.After(3 * time.Second):
+				t.Fatal("shutdown hung")
+			}
+			if !errors.Is(err, lifecycle.ErrResourcesRetained) || closed.Load() {
+				t.Fatal(err, closed.Load())
+			}
+			close(release)
+			<-joined
+			// In the run case the entry's completion notification follows the user defer.
+			// Close is idempotent and must retain resources even after late completion.
+			if err = held.Close(); !errors.Is(err, lifecycle.ErrResourcesRetained) || closed.Load() {
+				t.Fatal("retention was lost", err)
+			}
+			data, _ := os.ReadFile(logfile)
+			if !strings.Contains(string(data), "after shutdown deadline") {
+				t.Fatal("logger closed while work still running", string(data))
+			}
+			_ = held.Logger.Close()
+		})
+	}
+}
+func TestExplicitConfigurationAndPreflight(t *testing.T) {
+	setup(t)
+	t.Setenv("PLAIN_LEVEL", "debug")
+	t.Setenv("LOG_LEVEL", "error")
+	p := filepath.Join(t.TempDir(), "config.yaml")
+	if err := os.WriteFile(p, []byte("log:\n  level: ${PLAIN_LEVEL}\n"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := config.Load(p)
+	if err != nil || cfg.Log.Level != "debug" {
+		t.Fatal(cfg.Log.Level, err)
+	}
+	if err = os.WriteFile(p, []byte("log:\n  level: info\n"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err = config.Load(p)
+	if err != nil || cfg.Log.Level != "info" {
+		t.Fatal("implicit environment override", err)
+	}
+	var initCalled atomic.Bool
+	svc.Initialize = func(context.Context, *svc.ServiceContext) error { initCalled.Store(true); return nil }
+	if err = os.WriteFile(p, []byte("lifecycle:\n  drainTimeout: -1s\n"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	if err = run(context.Background(), p); err == nil || initCalled.Load() {
+		t.Fatal("invalid configuration initialized dependencies", err)
+	}
+}

cmd/go-omni/scaffold/version.go

@@ -10,7 +10,7 @@ const frameworkModule = "git.yuntuo.hk/k2safe/go-omni"
 // Source builds can carry an unpublished VCS version (including +dirty).
 // Keep this fallback in sync with the next release; installed CLIs use their
 // downloaded module version, which also has a module checksum.
-const defaultFrameworkVersion = "v0.27.0-preview"
+const defaultFrameworkVersion = "v0.28.0-preview"
 
 // This target is not a claim that the release already exists. Source users
 // select a local framework checkout until the module templates are published.

examples/program/.gitignore

@@ -0,0 +1,6 @@
+/program
+/var/
+.env
+.env.*
+!.env.example
+/.goOmni/project.lock

examples/program/.goOmni/projectManifest.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "kind": "project",
+  "templateVersion": "v0.28.0-preview",
+  "module": "example.com/program",
+  "generated": {
+    "internal/config/loadGen.go": "8a1a2746f46596a7893832ca411bd7e2d23978661943d322ee732d2c095cbe47",
+    "internal/svc/runtimeGen.go": "0eb681169112302add633cc7355fbd19844b01fa0b38b94625ec18127e5fb937",
+    "main.go": "36168d3e3fe822f74cede8eac3fffe5502174899e242c41526f6ad5cab7af4fd"
+  }
+}

examples/program/README.md

@@ -0,0 +1,18 @@
+# 通用程序示例
+
+由 `go-omni project new` 生成，入口、加载和装配文件未经修改。项目仅在配置添加 `once`，在 `internal/run/run.go` 决定完成即退出或等待信号；无端口、数据库、队列和业务任务。
+
+```sh
+cd examples/program
+go mod tidy
+go run . -check-config
+go run .                     # once: true，完成即退出
+# 编辑 etc/config.yaml 为 once: false 后运行，用 Ctrl+C / SIGTERM 停止。
+go build -o program .
+go-omni project check
+go test ./...
+```
+
+使用同版远程 v0.28.0-preview CLI 与框架，无本地 replace。源码发布前开发可临时 `go mod edit -replace git.yuntuo.hk/k2safe/go-omni=../..`，验证后移除此本地替换。
+
+配置、svc、Run 归项目维护；main/Gen.go 和清单由生成器维护。背景组件在 Init 登记停止与排空，已接受工作使用 WorkContext；未结束时不会提前释放共享依赖。详细规则见 [PROGRAM.md](../../PROGRAM.md)。

examples/program/etc/config.yaml

@@ -0,0 +1,12 @@
+# Project-owned. Environment references are explicit: ${NAME} or ${NAME:-fallback}.
+log:
+  level: info
+  format: json
+  output: stderr
+lifecycle:
+  stopTimeout: 5s
+  drainTimeout: 10s
+  cancelTimeout: 5s
+
+# true: finite run; false: wait for SIGINT/SIGTERM.
+once: true

examples/program/go.mod

@@ -0,0 +1,5 @@
+module example.com/program
+
+go 1.22.0
+
+require git.yuntuo.hk/k2safe/go-omni v0.28.0-preview

examples/program/internal/config/config.go

@@ -0,0 +1,29 @@
+package config
+
+import (
+	omniConfig "git.yuntuo.hk/k2safe/go-omni/config"
+	"git.yuntuo.hk/k2safe/go-omni/lifecycle"
+	"git.yuntuo.hk/k2safe/go-omni/logx"
+)
+
+// Config, Default and Validate are project-owned. Add project settings here.
+type Config struct {
+	Once      bool                     `json:"once"`
+	Log       logx.Config              `json:"log"`
+	Lifecycle lifecycle.ShutdownConfig `json:"lifecycle"`
+}
+
+func Default() Config {
+	log := logx.Default()
+	log.Service = "example.com/program"
+	return Config{Once: true, Log: log, Lifecycle: lifecycle.DefaultShutdownConfig()}
+}
+func (c Config) Validate() error {
+	if err := c.Log.Validate(); err != nil {
+		return omniConfig.AtField("log", err)
+	}
+	if err := c.Lifecycle.Validate(); err != nil {
+		return omniConfig.AtField("lifecycle", err)
+	}
+	return nil
+}

examples/program/internal/config/loadGen.go

@@ -0,0 +1,12 @@
+// Code generated by go-omni project. DO NOT EDIT.
+package config
+
+import omniConfig "git.yuntuo.hk/k2safe/go-omni/config"
+
+func Load(path string) (Config, error) {
+	loader, err := NewLoader()
+	if err != nil {
+		return Config{}, err
+	}
+	return omniConfig.LoadProject(path, Default(), loader)
+}

examples/program/internal/config/loader.go

@@ -0,0 +1,6 @@
+package config
+
+import omniConfig "git.yuntuo.hk/k2safe/go-omni/config"
+
+// NewLoader is project-owned. Register additional decoders here if needed.
+func NewLoader() (*omniConfig.Loader, error) { return omniConfig.NewLoader() }

examples/program/internal/run/run.go

@@ -0,0 +1,19 @@
+package run
+
+import (
+	"context"
+	"example.com/program/internal/svc"
+)
+
+// Run is project-owned. Return nil for normal completion, or an error to fail.
+// The starter waits for shutdown; a one-shot program can simply return when done.
+// Register background stop/drain hooks in svc.Init, not concurrently here.
+// Accepted background work uses deps.WorkContext(), not the early-stop ctx.
+func Run(ctx context.Context, deps *svc.ServiceContext) error {
+	if deps.Config.Once {
+		deps.Logger.InfoContext(ctx, "program.completed")
+		return nil
+	}
+	<-ctx.Done()
+	return nil
+}

examples/program/internal/svc/runtimeGen.go

@@ -0,0 +1,44 @@
+// Code generated by go-omni project. DO NOT EDIT.
+package svc
+
+import (
+	"context"
+	"errors"
+	"example.com/program/internal/config"
+	"fmt"
+	"git.yuntuo.hk/k2safe/go-omni/lifecycle"
+	"git.yuntuo.hk/k2safe/go-omni/logx"
+)
+
+func New(ctx context.Context, logger *logx.Logger, cfg config.Config) (result *ServiceContext, err error) {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	if err = ctx.Err(); err != nil {
+		return nil, errors.Join(err, lifecycle.Cause(ctx))
+	}
+	if logger == nil {
+		return nil, errors.New("service context requires a logger")
+	}
+	if err = cfg.Validate(); err != nil {
+		return nil, err
+	}
+	runtime, err := lifecycle.NewRuntimeWithConfig(logx.WithLogger(ctx, logger), cfg.Lifecycle)
+	if err != nil {
+		return nil, err
+	}
+	c := &ServiceContext{Runtime: runtime, Config: cfg, Logger: logger}
+	defer func() {
+		if p := recover(); p != nil {
+			err = fmt.Errorf("dependency initialization panic: %v", p)
+		}
+		if err != nil {
+			result = nil
+			err = c.Finish(err)
+		}
+	}()
+	if err = c.Init(c.Context()); err != nil {
+		return nil, err
+	}
+	return c, nil
+}

examples/program/internal/svc/serviceContext.go

@@ -0,0 +1,24 @@
+package svc
+
+import (
+	"context"
+	"example.com/program/internal/config"
+	"git.yuntuo.hk/k2safe/go-omni/lifecycle"
+	"git.yuntuo.hk/k2safe/go-omni/logx"
+)
+
+// ServiceContext is project-owned. Add dependencies without global variables.
+// Runtime owns registered resources; Logger is borrowed from the entry point.
+type ServiceContext struct {
+	*lifecycle.Runtime
+	Config config.Config
+	Logger *logx.Logger
+}
+
+// Init runs before Run. Register resources immediately with OnClose.
+// Register paired OnStop/OnDrain hooks before exposing background work.
+// Use WorkContext for accepted work; Context is the early stop notification.
+// OnDrain returns nil only after processing and final cleanup have completed.
+// Complete all registrations here, before Run can race with shutdown.
+// The drain name "go-omni/project/run" is reserved for the generated entry.
+func (c *ServiceContext) Init(ctx context.Context) error { return nil }

examples/program/main.go

@@ -0,0 +1,89 @@
+// Code generated by go-omni project. DO NOT EDIT.
+package main
+
+import (
+	"context"
+	"errors"
+	"example.com/program/internal/config"
+	program "example.com/program/internal/run"
+	"example.com/program/internal/svc"
+	"flag"
+	"fmt"
+	"git.yuntuo.hk/k2safe/go-omni/lifecycle"
+	"git.yuntuo.hk/k2safe/go-omni/logx"
+	"log"
+	"os"
+	"os/signal"
+	"syscall"
+)
+
+func main() {
+	path := flag.String("config", "etc/config.yaml", "configuration file; empty uses Default()")
+	check := flag.Bool("check-config", false, "validate configuration without initializing dependencies")
+	flag.Parse()
+	if *check {
+		if _, err := config.Load(*path); err != nil {
+			log.Fatal(err)
+		}
+		return
+	}
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+	if err := run(ctx, *path); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func run(ctx context.Context, path string) (runErr error) {
+	cfg, err := config.Load(path)
+	if err != nil {
+		return err
+	}
+	logger, err := logx.New(cfg.Log)
+	if err != nil {
+		return err
+	}
+	var deps *svc.ServiceContext
+	defer func() {
+		if p := recover(); p != nil {
+			runErr = fmt.Errorf("program initialization panic: %v", p)
+		}
+		if deps != nil {
+			runErr = deps.Finish(runErr)
+		}
+		// Unjoined work may still use its dependencies and logger. The process exits
+		// unsuccessfully; resource retention never means the work completed.
+		if !errors.Is(runErr, lifecycle.ErrResourcesRetained) {
+			runErr = errors.Join(runErr, logger.Close())
+		}
+	}()
+	deps, err = svc.New(ctx, logger, cfg)
+	if err != nil {
+		return err
+	}
+	if deps.Context().Err() != nil {
+		return nil
+	}
+	done := make(chan struct{})
+	// This reserved drain proves Run has actually returned, including its defers.
+	// Runtime bounds the wait even when Run ignores cancellation.
+	deps.OnDrain("go-omni/project/run", func(context.Context) error { <-done; return nil })
+	logger.InfoContext(deps.Context(), "program.starting")
+	go func() {
+		var result error
+		returned := false
+		defer func() {
+			if p := recover(); p != nil {
+				result = fmt.Errorf("program run panic: %v", p)
+			} else if !returned {
+				result = errors.New("program run exited without returning")
+			}
+			deps.RequestShutdown(result)
+			close(done)
+		}()
+		result = program.Run(deps.Context(), deps)
+		returned = true
+	}()
+	<-deps.Context().Done()
+	return nil
+}

lifecycle/README.md

@@ -96,3 +96,7 @@ err := app.RunContext(control.Context())
 实际使用时 App 和依赖通常先初始化，再由并发监控回调请求退出。资源在 HTTP 排空完成后由调用方关闭，并读取 `control.Err()` 合并清理期间报告的首个故障。通知本身不会关闭资源、执行 os.Exit 或发送操作系统信号。
 
 `RequestShutdown(nil)` 表示正常停止，非空 error 表示故障。Controller 保留首个非空故障，重复调用和并发调用安全。`Cause(ctx)` 将符合 errors.Is(err, context.Canceled) 的取消原因视为正常停止（包含新版 Go 的信号原因），保留其他取消原因和 DeadlineExceeded。显式 RequestShutdown(err) 上报的非空错误始终由 Controller.Err 保留，包括包装 context.Canceled 的错误。App.RunContext、ServeContext、RunWith 均保留这些异常原因，与网络适配器无关。
+
+## 通用工程入口
+
+`go-omni project new` 可生成不监听端口的普通 Go 程序，直接复用 Runtime。入口监督项目 Run 的完成，并与 Init 登记的后台工作一起排空；Run/Init 异常和资源保留信号会传递到退出状态。完整运行契约与配置见 [通用工程指南](../PROGRAM.md)。

reports/httpSafetyAcceptance.md

@@ -31,3 +31,13 @@
 旧 nethttp 手写普通路由新增默认 8 MiB 限额，大请求应显式配置；生成契约默认 1 MiB 保持。取消后的等待默认 5s，需计入服务停机预算。手写资源拥有者须将运行错误传给 Runtime.Finish，并在资源保留信号下跳过自己的额外关闭操作。自建 goroutine、Hijack 后的工作仍须登记后台生命周期。
 
 自定义 Runner、独立 native/http2.Server、反向代理的额外限额由各自拥有者配置；使用 WithTransport 获取统一装配。请求体、multipart 单文件和幂等缓存限额保持各自用途。已发送的流式响应无法撤回，先完成有界读取再执行业务。
+
+## 远程发布验收
+
+空模块缓存安装远程固定版本后，10 组生成消费者和 98 项发布检查通过，耗时 107.57 秒，无本地 replace；覆盖上传限额、取消收尾、HTTP/2 断连、生成项目依赖与日志保留。标签固定在 `3b00bb55d189cbe480c7d15c8d14bcd09d3f2d52`，见 [远程验收记录](httpSafetyRemote.json)。
+
+模块校验和：`h1:IYc1zEBQX6GTPvORAC9Q7ezlzKlGn1nVnK8T68L/DGA=`。运行命令：
+
+```sh
+npm exec --yes --package=typescript@5.6.3 -- python3 scripts/verifyManagedRelease.py --version v0.27.0-preview --report reports/httpSafetyRemote.json
+```

reports/httpSafetyRemote.json

@@ -0,0 +1,292 @@
+{
+  "passed": true,
+  "frameworkVersion": "v0.27.0-preview",
+  "frameworkSum": "h1:IYc1zEBQX6GTPvORAC9Q7ezlzKlGn1nVnK8T68L/DGA=",
+  "freshModuleCache": true,
+  "noLocalReplace": true,
+  "durationSeconds": 107.57,
+  "checks": [
+    "remoteCLIInstall",
+    "freshModuleCache",
+    "fixedVersionNoReplace",
+    "contractChangePreview",
+    "persistentLogicSignatureFailure",
+    "businessSourcePreserved",
+    "fixedConsumerBuild",
+    "rootGoRun",
+    "nethttpAndNativeSignals",
+    "listenerReleased",
+    "default404And405",
+    "goOwnedErrorCatalog",
+    "unwrappedDownloads",
+    "rawCallback",
+    "multipart400And413",
+    "nethttpAndNativeTransfers",
+    "sharedGoCatalogExport",
+    "documentOnlyErrorSelection",
+    "workspaceCheckNoWrites",
+    "staleCatalogRejected",
+    "twoIndependentServiceBuilds",
+    "initializationAndListenFailureCleanup",
+    "drainBeforeDependencyClose",
+    "generatedConsumerRaceTests",
+    "errorParamsAndInheritance",
+    "manualHooksAndScalars",
+    "dependencyFatalShutdown",
+    "fatalProcessExitCode",
+    "initializationShutdownNotification",
+    "configuredBuiltinEndpoints",
+    "projectHealthEnvelope",
+    "endpointConflictCleanup",
+    "responseArrayNullableNull",
+    "primitiveAndDynamicArrays",
+    "strictRequestPolicies",
+    "declarativeMultipartBinding",
+    "backgroundStopDrainResourceOrder",
+    "backgroundInitAndListenFailureCleanup",
+    "backgroundTimeoutRetainsResourcesAndExits",
+    "generatedIncompleteHTTPDrainRetainsDependenciesAndLogger",
+    "remoteHTTPClientRaceTests",
+    "remoteHTTPProxyAndTimeouts",
+    "remoteHTTPHeaderIsolation",
+    "remoteHTTPPoolAndDrainBudgets",
+    "remoteHTTPExample",
+    "remoteExplicitConfigurationRaceTests",
+    "literalAndRequiredDefaultReferences",
+    "remoteCheckConfigBeforeDependencies",
+    "removedImplicitEnvironmentRules",
+    "remotePreciseModuleDiagnostics",
+    "remoteJSONSuccessStatuses",
+    "remoteRejectedStatusBodyCleanup",
+    "remoteCopyTypePreflight",
+    "remoteEmptyCollectionTypeRejection",
+    "remoteLoggerTimeZoneIsolation",
+    "remoteCORSPolicyRace",
+    "remoteCORSErrorResponses",
+    "remoteCORSTransports",
+    "generatedCORSConfigOnly",
+    "remoteUnifiedBodyPolicyTransports",
+    "remoteBodyLimitsBeforeMiddleware",
+    "remoteHardLimitConflictBeforeServing",
+    "remoteCanceledHandlerCleanupBarrier",
+    "remoteExternalServingResourceRetention",
+    "remoteAdmissionCloseRace",
+    "remoteRuntimeFinishRetainsHTTPDependencies",
+    "remoteHTTP2DisconnectedHandlerDrain",
+    "remoteNativeEarly413AndBusinessHTTP200",
+    "remoteHTTPSafetyExampleBuild",
+    "remoteTransactionStages",
+    "remoteTransactionCauseChains",
+    "remoteCommitOutcomeUnknown",
+    "remoteCancellationOutcomeUnknown",
+    "remoteTransactionPanicAndConcurrency",
+    "remoteTransactionPublicErrors",
+    "remoteTransactionExample",
+    "remoteI18nRuntimeRace",
+    "remoteI18nGeneratedConsumer",
+    "remoteI18nHTTPBusinessInvariants",
+    "remoteI18nSourceOnlyFallback",
+    "remoteCLDRSamplesAndBrowserConformance",
+    "remoteTypeScriptConsumer",
+    "remoteI18nCLIExtractionCheckExportTypes",
+    "remoteI18nNamespaceIsolation",
+    "remoteBrowserRaceAndFailureRetention",
+    "remoteJSONReaderCausePreservation",
+    "flatFieldComposition",
+    "copyxThreeEndpointConsumer",
+    "explicitNullAndMoneyPolicies",
+    "fieldAdditionWithoutCopyRuleChanges",
+    "middlewareFactoryInjectionAndCleanup",
+    "optionalRepositoryPreservesBusiness",
+    "generatedUnifiedConfig",
+    "jsonYamlXmlAndCustomDecoder",
+    "configValidationBeforeDependencies",
+    "configEnvProvenance",
+    "configExtensionPreserved",
+    "configLoaderDriftCheck"
+  ],
+  "sourceHashes": {
+    "lifecycle/runtime.go": "d34fb26879932153671b9cbd164daae484b23dca08b8a3be5b1b89f8f6168e47",
+    "lifecycle/phases.go": "6e72499d2c5fcecb57cf712e76e3a03fed61a4caf528f873f2058291a8ab0b4d",
+    "config/lifecycle_test.go": "fe31c371acc3b2df2f58ecfb7b6a0f29d444410f43c0d49bad6cbf72a1a87248",
+    "task/task.go": "acb1a2cc0e26029331065545582c30e0c547e3b6869f7d8b16c7d25ab0077545",
+    "cmd/go-omni/scaffold/templates/api-runtime.go.tmpl": "e8575c04b0923d924d96e4334731313076284fd068c4990715b7a07a2724f969",
+    "cmd/go-omni/apigen/templates.go": "866a7ab9cc28f987645785203213e10722490970d5a1fd3c060d88db8b1278dd",
+    "config/project.go": "169e13921afa6a9336fcde3310675580799335ce55f076cbe60cdf3cfbd8cac2",
+    "contract/bind.go": "25ef07654abe42fe5f7e9cf5e5aa3bf102b311502bdbf16c0346970f87ee3053",
+    "contract/policy.go": "2c8e7efb07d59fea2c00ab39694d4df52a5bea6495ce23cac1c470584af74da1",
+    "contract/multipart.go": "db0377599b1b8b39246d41129513e8187109e44c1892971244d581c22ccc8ecd",
+    "contract/file.go": "20dd2de17e4854d452afc3c65f0293d504fb8fc25e91583ef45207fdab30948d",
+    "cmd/go-omni/apigen/business_test.go": "3b484352282d945f5a58047682079e3d64d4b0bf6ec6bafc23151b1197bb3942",
+    "cmd/go-omni/apigen/generate.go": "4bf8f3cee4d2fc832c344f6fae7446a56fbfd673cb3816feab926e1d39c7eca3",
+    "lifecycle/controller.go": "1fb9393df1908afed93d87a1bf3ecea8d79d78e437a656b56bb7f1e5f6e51d31",
+    "config/endpoints.go": "9f5123f962d52b71e5b73d5942316170875e895129a94e8b669ce782969ef27d",
+    "health/health.go": "41f07f27a7fdcfa7973c2c554a22b73129ebc5d44e945e70e054e1cff24ab866",
+    "httpx/response.go": "99e29724e4fa51d2c7ec1a52892c24ac5daf210a2ee547c5e69a175015298efd",
+    "app/app.go": "2e672b3f6376049dd9695f799698439909f1d649d4338d13478e0dbf1de68800",
+    "app/transport.go": "8c665f47447d9839bba7ba3efa290316be9635179d2276b0da0d0f8eda3842ec",
+    "scripts/verifyManagedRelease.py": "6860e3f440c4d4f51a55085e50066b1a43cd31d5068c2f7a01a708c16823aef7",
+    "scripts/verifyManagedProject.py": "b0e4b1aea4f44d61470c35c41f971e0882ae36b0eb5df2be190400d62fc60a18",
+    "cmd/go-omni/apigen/managed_test.go": "e0b2b5aa6c4d6383590b467d57d7b4e00505ca35d6b6cde2475e4ad574041e94",
+    "cmd/go-omni/apigen/testdata/managed/options.go": "30d48e4b5aab476c887ac53cc89b48b2b7e250c8cd25e55fecb49bb2a3589247",
+    "cmd/go-omni/apigen/testdata/managed/background.go": "fb357b5deefd5187f2df406be5189fc4d57da857bd55b474f4726bf065c77167",
+    "cmd/go-omni/apigen/testdata/managed/client.go": "cb4a07539adbd163c13fc6cbb914518506b0c60a88473589f212f3406e763e4b",
+    "cmd/go-omni/apigen/testdata/managed/phases_test.go": "94a5787218c0d92159b473d390197858241ede2cab591df0976e611ed279dcfe",
+    "cmd/go-omni/apigen/testdata/managed/shutdown_test.go": "b078bd9052e513ab6173a1e65cf54b28d3cfad445cb50518d9e2e76736071047",
+    "cmd/go-omni/apigen/testdata/managed/consumer_test.go": "589e2c54d9ad7f64e88ac556329a52062a27b4e898deb9a97feff200787c32c1",
+    "cmd/go-omni/apigen/testdata/managed/operations.go": "a1d91744abe020cbfb476512cffb7dad422a95da1c3be6957fdcfe27c361030b",
+    "cmd/go-omni/apigen/testdata/business/accessFactory.go": "2f982cf39b5e1a4be98596ce5d0a296af0fbf8c94616543a268e67ec376f31b4",
+    "cmd/go-omni/apigen/testdata/business/client.go": "d4cbaeec18dfb3a0e2821217e8eb0515000e351a745a93ec811dabca44e58c8a",
+    "cmd/go-omni/apigen/testdata/business/consumer_test.go": "e4159862a729ca2c5c9699840cc16a56350fc2914c43841f08946e9a6e9c8091",
+    "cmd/go-omni/apigen/testdata/business/operations.go": "11ded7921a0753f22975c525e334e3d45366143625e41d24fe500504e785c64c",
+    "cmd/go-omni/apigen/responseShape.go": "5b705130b66a3d4aaed842025b75abe54e6427acac8366366ca88ae9862429e1",
+    "cmd/go-omni/apigen/documentRefs.go": "7b841a668154d872493104eda0f9049340c67d9323eb99f1621a1ef6ba343891",
+    "cmd/go-omni/apigen/catalogDocument.go": "94df60328b2f105c35b73d9c6362ea14abadce6cb18e4d9921193d2d46854252",
+    "cmd/go-omni/apigen/workspaceCatalog.go": "c00784220b379ed80deb07c060532b756cbc47434ecb8b1ca10bc12b12159328",
+    "config/references.go": "ea709ddb32a9c5601662a875765d376b8490c4c766ecdb4365f462b5a2b10e16",
+    "cmd/go-omni/apigen/arrayResponse_test.go": "9e3e4475f76683d3346d349cdfa94e9e75cf913ac6979bd7a4ed86628466d879",
+    "cmd/go-omni/apigen/testdata/arrays/values.go": "d5e7f3adf12aabb301f46c296e8c894a7b2f6f70a6b6e7e02c74da7f1fd17bc5",
+    "cmd/go-omni/apigen/testdata/arrays/consumer_test.go": "435932f2952ad897943e2cda83b04eccb2950579d8d88772661541e1e2a2333d",
+    "cmd/go-omni/apigen/composition.go": "7ed3761b27d9c932d8ddc43e63c2aca798bdbe38f2b40571af8916c8401ea650",
+    "cmd/go-omni/apigen/generatorConfig.go": "78db0c7808cf6ec997c5b64a4a5fbea11b74049709bc5900ccfbc5d8dabebbc8",
+    "cmd/go-omni/apigen/copyConsumer_test.go": "e08ae4daed5dd25ab89d8872f653caf19499984dcaddc9835c13884c410fc0c3",
+    "cmd/go-omni/apigen/generatorConfig_test.go": "a6d8c8ebea5f1accf0e37dd044e57b48e422821fe75086d8d2eb3abe3acb147c",
+    "cmd/go-omni/apigen/middlewareFactory.go": "cc0220edb3eff25d7f66b2c37e206455f8730a2b909613713322bee7caf72303",
+    "cmd/go-omni/apigen/testdata/composition/accessFactory.go": "e1e5057ff79f806b3218e93249e8191d097b5c4844977204a8c32848443cba33",
+    "cmd/go-omni/apigen/testdata/composition/domain.go": "ab27ebd7ad5e3ed5505a2aa268b9b5ceedbb01477b59011bec63bb270114078b",
+    "cmd/go-omni/apigen/testdata/composition/amount.go": "f2d1834502d71d9ecf72ebe3b1077e5ef41f44fd816abd4617ac19f9bb962fdd",
+    "cmd/go-omni/apigen/testdata/composition/copy.go": "32d37d6f1f0e9aa2409aeb90b052801d1cdca70e504c2dd294cdae01422c9cb7",
+    "cmd/go-omni/apigen/testdata/composition/client.go": "19102e191c0471cae9e7405623906d0d804865c40b80ff1d5b240a41ceab6a4e",
+    "cmd/go-omni/apigen/testdata/composition/service.api": "01d230d5409756e2f3eb602a7fe065efa7d9599f7a4089da4bf8f07a2474444e",
+    "cmd/go-omni/apigen/testdata/composition/consumer_test.go": "74aaf60318cd0de67495fc9142b3f67c3b6e232bb48b46b3e134de5aadd225ad",
+    "cmd/go-omni/apigen/testdata/composition/dependencies.go": "edc153204b06da00c0e45c52db43a4a22f8ffe22c4a6d3f3ebec0137b861f84d",
+    "cmd/go-omni/apigen/testdata/composition/converters.go": "ecdcfe31c75ca815dab8d1a82533b12cbbd40e12b3a5c444e815097f6c4df08e",
+    "copyx/check_test.go": "4095de3e3ba946573edb0b2baad5b492eb559565745693e144ca008eb740e1a2",
+    "copyx/check.go": "aa53985a2d8b73a18c51d112552bfecd06b60079cd119ebeed5ef4a5d3b0db22",
+    "copyx/options.go": "edea2f3d2043bf813e56dedf0aea319aaa52301d3b589f41fef986e33a77dc32",
+    "copyx/copy.go": "179a5a1be871813765074d945aa341945d2a4a9a42928e2b30e9839f9795aa9a",
+    "copyx/graph.go": "ae6a2a11a8175033d327b580cd570c97fe9d2ddb814bb50884cc19a90766badd",
+    "copyx/benchmark_test.go": "b1bf408957cadea47b47215ffb099d140d5d1a2eb061024a6d0c1d769f469a79",
+    "copyx/copy_test.go": "89b65a6281591d7cd5823cc1c7d2c384c6bd446ef06aa1763ddc3acaa84dfb4a",
+    "config/decoders.go": "6d31f67c82563c2d63e37ad1ce9b9fbad6232b2b785b9b58dd025be857f0fc28",
+    "config/config.go": "cbf09c158a9add8289befd9960f911a8cf42de0b840a57278bc71bf800121ec8",
+    "config/cors_test.go": "b40e76dd943f28c80a06eeb2dc74a536b217c4918c4a21d7de870404483a377a",
+    "config/errorCatalog_test.go": "a9cca5233da1ebf9280a022e10ff07e50f99cf01eac8ae70b905fe12665e3d9d",
+    "config/suggestions.go": "5220f78bc8e4fda44f4cedc6cc6227895417d83d49eaef3f54711f3a0f9e1245",
+    "config/http_test.go": "975dc288486ba537cf7fd7ee87df792ba7eceed6ab0a58e6a5c0660ce724ab9d",
+    "config/response_test.go": "b4ccb111f813f80dc180a7ddb11034a409b9409cbb1b57e654c04d678465d201",
+    "config/projectAdvanced_test.go": "48b5493fe364e1022d63f1f2b556e2e1554b14af8f994074ec9b048fc6108fa4",
+    "config/file_test.go": "019ad4356838a592826daaf3bdcc7706b74a0d7782abcbe9bd6aba161aaa6576",
+    "config/moduleDiagnostics_test.go": "68b9bba485617e3cde57773b8c24cd9554636f6364151bbfcad48548408c83b4",
+    "config/references_test.go": "e19f0a42bbe08d1a723aff63e2d77d22feba08da98ecf5d47aa675e7105da850",
+    "config/errorParams_test.go": "fe61921a2e5fbdf32a623299fec42799287b0af1ab19b2f8fdd4bc97583e582d",
+    "config/http.go": "d02858d522ad63e86185f5d87d3fec9718141c75b7199fe75d0894dfa016d24d",
+    "config/loader.go": "50a2347960cc98f337b7a179e3054af0bfd22db879b58bee4ffd09e3f693d051",
+    "config/file.go": "2fbf4cd55d13944d7a7a208696f4a845a2089058d5f6e463c1e769e56bf77404",
+    "config/diagnostic.go": "cf818cd90941a5c2d9a6279dc4c3b90d71495db22846625fdf769dadefcf077a",
+    "config/bind.go": "0eabe1534eb671f13c938021183a1f3df829283d6fb587b849d22253dda278b2",
+    "config/clone.go": "6146bf8a7d7549d975142a843db5c6f95c67e98b62cbd98e20c77842abd38040",
+    "config/endpoints_test.go": "3368cd6af3e5902a1a4f7ea9f67e2da9e3d525f5c63f7e78aaeaae8fdfbf8394",
+    "config/config_test.go": "112202bdd153e9e87a43629b842e02caaad54e9516e1f7cd18c301f74cb69cc7",
+    "config/loader_test.go": "854de1586e64ac00acd7970be929af8a1b17d9a027bf92544f6221ccef38ceb9",
+    "cmd/go-omni/apigen/configLoader_test.go": "75c47861be382558434883d25c8deb1a567bd305290db624e572d2dcf302afbf",
+    "cmd/go-omni/apigen/testdata/configuration/consumer_test.go": "0cf2d8b6fabf8dc4652d33cadb5a462e6f3a527463d8965fcb54123ae6cb6cc4",
+    "cmd/go-omni/scaffold/templates/api-load.go.tmpl": "c8089dfa50ea09de60a18f06463e83e8f0fa9fbb6795fd615e37822d7b2ab708",
+    "cmd/go-omni/scaffold/templates/api-loader.go.tmpl": "847ac407827808022dcf493823b58671e1ae50349b173a5e4500580e07c64150",
+    "httpc/config.go": "08241015b758648b0eb793e1856b88898ec57d8021c8e542db7d1dd6a2dcf2e6",
+    "httpc/request_test.go": "ae410eaa2cac54bbc15515a524387dde7bd7aa61a8fcc8e820108cbcc85c7b98",
+    "httpc/request.go": "43c1a4611331c8ac81eab98d5782fe8d4d271c14daa219e8a2134e029b65064d",
+    "httpc/status_test.go": "4f71d3f4aede466c02f978c5b4a4d3ffc83edee5916ce8d0505d01878ddef2a5",
+    "httpc/client.go": "a5a99b70bd1b1828a260bb41a6d9dc42d85f18a6b33ec822315374871d6af959",
+    "httpc/benchmark_test.go": "3ac0ccfb227b00fcbca42f89686fb67e3e00f4ed23ac5dfa686663ae18843a07",
+    "httpc/config_test.go": "84bc068fdc7964ae16c133374ecd6e07278253e33cea132ebcafc681378d7559",
+    "httpc/client_test.go": "972ebd2efab618629e394484c288afe4e675fcfe0c50121d9fa9071680d6e763",
+    "httpc/json.go": "e4a3caf19f24c3f58494311cd887dbb00acbdb4d9efc1f36988e19cb0f9abe7c",
+    "examples/httpClient/main.go": "8572f68d1bdbe9e3ce36b6f53d6ac7ef98966e0ac596ba57bb0811314a832eb5",
+    "examples/httpClient/main_test.go": "32f5513b2a2702214882c0163e0686548d8eb527977cde23829b54175d95010e",
+    "logx/logx_test.go": "0f99eff445decdd81a55b3d5374c22d2e038d2a4748adb2c9367d6d03e481671",
+    "logx/redaction.go": "e288c01cb0e30a79855b9e1b886a802c5614298aba5f39b2619eafb1f187f9ae",
+    "logx/adapters_test.go": "f0c57ca90075c82f9552ec43e58ab0613b43dea89411d9db50ba5fcb5be3dddf",
+    "logx/production_test.go": "5a6f957d409d657a1e712e72aab3e3275b2ba21dc81dd3be69523c90d47cc458",
+    "logx/timeZone_test.go": "523a864a1d55e32a770b9816634d6445ad468cab2e7d8d86588b1c428ec04824",
+    "logx/adapters.go": "5b558685e88cb37889238f73e9670d4db2b509fd39d512ddfca25de1b5f4aea8",
+    "logx/logx.go": "18dd28f8378e403773e238d1c8ce4acd05838d2863475ab7a5e278f5ba7cb6fb",
+    "logx/timeZone.go": "1b82737362f880f4a8461fd20637ef64eef5a5db475a49e0c9daa27a6ca7b636",
+    "logx/rotation.go": "e278c5ffbdba36c39b15c8b31299abe402695edaf525eb5b03d4328cf35fce61",
+    "internal/configdiag/error.go": "a25f9f398cd0e5ea1a0d049c8a7c264c85be67c469619b41220cf56afffdbda6",
+    "database/mysql/mysql.go": "e5f95b97dd79eb64d493255d2fd2f5895538131021eb8a6068de8ff6f484702c",
+    "database/connector.go": "5a973ea4bc53fee2b72f1925f5cf4e3d83a3c935a1455406f4a7abd46c47c007",
+    "database/database.go": "5cf05972b56870d89da5290e3b0db777b0253c3b4214cee3d47ab7fa6d76a263",
+    "examples/developerTools/config.yaml": "1e672ba1b0b16a417840a09468f785776c51408ee973b55b1910cb736a8e29d9",
+    "examples/developerTools/README.md": "3ba0d700dc3e3788a2a57367273b8d6b0f2acbf2f6cf38149edeef84ce898908",
+    "examples/developerTools/main.go": "a799d3106b4a64258b7c1cbad9c776cab840526795416b07b114628e3bd4c440",
+    "cors/cors.go": "a0feb191b5ecc43b0a0c889af5c1ec960fdc55bfa813aff49413008077e64f70",
+    "cors/config.go": "973300087dee87fd35bb56a2c40b6ace75f85b08e6749cc509421aab9135e2e4",
+    "cors/cors_test.go": "49b20eb72ba4c40b949a711fba0bdcd342d793a8a010771204e696c563b3e08c",
+    "app/cors_test.go": "7dcfcbb9c605a16bbd5455177a1f527dbb18f673e6ebb2b93d7b874c64c5d56a",
+    "cmd/go-omni/apigen/corsConsumer_test.go": "8b5ce07474f50d89ba1d7d155b433e7103785b350db13df8cacd527b7070e240",
+    "cmd/go-omni/apigen/testdata/cors/consumer_test.go": "677c559b8c6fc77aa6d8a69c0c1296f1fbefaa7f2f64cf80609dbe4027e254ab",
+    "examples/cors/main.go": "39d76c4e2a4929f18f2acbfe03ab10c50b7276e56345de4d12eb962b5f6cc5b7",
+    "examples/cors/config.yaml": "a78f83433810cb385ac9a8debbeb6932ebef71d85df073afbfc1d928fb7bf89f",
+    "scripts/corsBrowser/main.go": "2654778e9c32829f6dadefe572551f9feb891da110741a08bf9243c7284c3ba2",
+    "database/transaction.go": "037f14ed495e6d024e13e2033c2e469b138dc5c1e1d6f6a9a73e723e094e71e1",
+    "database/transaction_test.go": "b8fb122c145836c07ca062dc8c89c07ae7482885d33c3f2c239cca21e97b72d4",
+    "database/transactionResponse_test.go": "bc59b17605c5b5e051fc987caf6dafbbb5d71f4b1380a5ceec8f2dafaafb6af7",
+    "database/mysqlConnector_test.go": "db5a9f5a99fd46e8e84c4452663704172ddc26a57ad6af84d3165041ff5357e9",
+    "examples/transactions/main.go": "ac2a17556b63c0bbb8a5c726381b6929df235da089549937a70d3696e2cba3f2",
+    "examples/transactions/demoDriver.go": "950b5f9bf0d20b8b2bc7590d502e110f2815fc394df789cac39e324149870ab6",
+    "i18n/bundle.go": "cd0b54e779fa9f8e3a1b5d4c7456ae06f0f39618365362de329d4b61104abb93",
+    "i18n/types.go": "cc912f7c7dc598de758cec79568fd0bdfac6cab8a8333a6ce0570680236d415a",
+    "i18n/plural_test.go": "ad3a430f370bc51503aa5bce335dcb5962f6e8226f2925956ddd419fd9c230d8",
+    "i18n/export.go": "99608af1d487fced1bba49b77157e7a1f51afb4341fbb607f09920dfca94155a",
+    "i18n/pattern.go": "1c7a91e48f449124d2de90abebd698401aef93896fcdfcf24a83e12a048c5192",
+    "i18n/README.md": "11a933abe712c961ca1c3b138d4440bc440a7b4c6e30654849e604efe4be056c",
+    "i18n/plural.go": "9b69e23568a4ea240d5d4bd2c62237932245a8a91aa451386f4a7d9d76d774f9",
+    "i18n/load.go": "6e43d781ba90db6de78d2138e496161c391797a735211cae7342abebac2c5618",
+    "i18n/bundle_test.go": "f9e30d36955722f51e7d9dfe685515441451459547a3235b97064de7dda4d8f9",
+    "i18n/i18ntool/extract_test.go": "dd62077d190e4264348f18e8f86d25e324eebf2d471918f27da8f0c552bf46c6",
+    "i18n/i18ntool/extract.go": "f0ab49435f61750b06ee8105ff016be5fe06c8404f90163708d9f7e423ae89c0",
+    "i18n/errori18n/errors_test.go": "2c2b74b1752d4367035c9f6b9f0f79bd05dac583f37f4e4de97d2163e667be4d",
+    "i18n/errori18n/errors.go": "539a9eac6b841a566bc808363e9505226c7510d5dc277da621dbefb16cb06ecd",
+    "i18n/browser/runtime.d.mts": "fd2f18dbb6d1b1dfe2392a5e0831354f0fb2ac8815328d8b422ab79503889ad7",
+    "i18n/browser/runtime.test.mjs": "83b219f3b72cdeb417f6223f9f0942ef8d3b43d5051b1c66dc475c7634d65acf",
+    "i18n/browser/README.md": "8a3de821c6cdf57c99ee2b56fa0deeb7557b9d11a9a77bf05b00c1ae22bf34ab",
+    "i18n/browser/conformance.mjs": "95b7325ef24513b53eb5b8d3475fe3c5c7c56bc2da2cb1aa74e097b2ee410623",
+    "i18n/browser/assets.go": "a20c679902c5d96dba13b0df31ef98e3516f0ebdd1c403740a6a720a412b0b84",
+    "i18n/browser/runtime.mjs": "a38f6378a835661ee9198ff910eafd04f4e56051c113d0637703e59e4ae3cd3c",
+    "i18n/browser/testdata/consumer.mts": "84e3e26d2d86a03b30e3fcd27c3bb51c268ac89ef115f8def274321250b46e08",
+    "i18n/cldr/LICENSE": "220ba0e1c43b99530d2d5bdb892a99dca0989414f51ab695ecd90163eaa1ec3b",
+    "i18n/cldr/README.md": "cd5aef06e415cf21913a5b8736c29abbc02df449868c16cd08be8aa7e0c8fea0",
+    "i18n/cldr/plurals.json": "ce19668400e9f7904e8b3939d1f0a2872fe8da7bdea9f45f5d50b3a2bac3b382",
+    "i18n/httpi18n/http_test.go": "1f0266d2d2a54bfe767efe76bfedce6130f6c988dd04be801416336a95a5d606",
+    "i18n/httpi18n/http.go": "ac22eeb795b62b74d0b9a233b6fb79a337f35d430e6a136fb31f643ee4512f0d",
+    "examples/i18n/index.html": "7d0c9e1fdaf96c883cbe8e671ae094d83c2742a9f76b820649d58d62f4944c12",
+    "examples/i18n/config.json": "c3e12efcedbfc6a8ca73cae9cd4cc3617ee363af8747aec630808e6f5e1eb682",
+    "examples/i18n/README.md": "bf5c3ae49b921b1c25d06e19d5ecb743f349ea9d085b9d9da79f1391a29fa9e1",
+    "examples/i18n/main.go": "3f8599781e423a9e3a968f5310fcc80d2daf5f09b733050c1e13c4fea589f29e",
+    "examples/i18n/main_test.go": "c99f736841fe579d2134762d4962da73d6ab88090e5921ce8c26edf5134bee9b",
+    "examples/i18n/locales/ui.en.json": "fa8b210ad1a78baae8f444420c983c5498025a1a3ea0bd15d64d8125629bee42",
+    "examples/i18n/locales/ui.zh-Hans.json": "04761003bea2a02b1e746a1f458f50fa2e0fdb3706d02bc5cb5a4f16378c5021",
+    "examples/i18n/locales/errors.zh-Hans.json": "d9113b720f4c284b90c41a6db4a867d272db4e951cd284eeb00ca69e3fc21385",
+    "app/i18n_test.go": "4d6125b78c33c7df759584b84f791d9a041673d6536503c6671a71e20b588d39",
+    "errors/localization.go": "a047c33e9c4ad9ca10aacfa0800dec51a5db788c1299fba0fb9b361abef41c85",
+    "cmd/go-omni/i18n.go": "be95a89de3fcc34baaea76669f30616902b0f5d7d6ef018e9c29a8e38106fb6a",
+    "cmd/go-omni/apigen/i18nVersion.go": "c4187e5d77164b8e906294b63e8d351db49a6d587b4f77a32529f6a4b75cb1c9",
+    "cmd/go-omni/apigen/testdata/i18n/consumer_test.go": "b62ad30f5912c50e1f6bb1737fd75430ead113989990acb6dcdc93f5d88de0af",
+    "contract/policy_test.go": "d1ea81c923dda58ae75323cc1eb9773517e63180153dbdf19eb35a634c9890db",
+    "app/body.go": "4064b96fc38c5b75ec17f0d82e0dec79242640c4d0903bf544e4fda057e5397a",
+    "app/router.go": "b0418e18fd546b855a4cce9ff19efc25b274d9b9c52144e12338bb5d97a5be9f",
+    "app/requests.go": "c4cb453e8215ed594e6755b256b4b1bbcd3b870584f4be19480d4dd1b9e0aa3d",
+    "app/bodyPolicy_test.go": "505afa7bcc3f70009ef2af2c455e377277db01c2b883c8e5204de0cbebf25cbb",
+    "app/requests_test.go": "b008b5599e1f5eea01a08f15220588bd581a2d5e98658d53f0acb273dd946137",
+    "app/transport_test.go": "10f086eeb77e3b11e83768bbbb0372aa68056a8c8839a18edfaf597b5acff689",
+    "httpx/context.go": "e3a7d3cd31bc6bddaf21c2be35887cf5c85e69ec5e6ff82178884cb0e4696ffb",
+    "internal/httplimits/limits.go": "98ba40ceda78fcf4b08d51b0851de851329f568fd35b0a4aedefd4b48a43e780",
+    "lifecycle/runtime_test.go": "ccd302f78535215bea69d7c8ad8c812c79c52cca087353358206cb6b5926d34b",
+    "transport/http2/server.go": "e0b7fdb3069583d042df5117b36a3fffc423ee452b0a9da162e3604fcce80b49",
+    "transport/http2/lifecycle_test.go": "2a298b8e466ff4145105338904ec5d9e19087c91d829d6ae5cad8c8b1ee05b15",
+    "transport/native/server.go": "8c2fc503bc157265838b453bfe289ec68eeb2bdaf63f6dd1e585536a8278ba0c",
+    "transport/native/earlyReject_test.go": "0fd598e24199beb55bead10d741d739f7361345584c4430b4a97c35d59d62774",
+    "examples/httpSafety/main.go": "4651b3806e7a8030101ba6a70794fcc18a50d2939fe0a59d7f80bb4a7de30f15"
+  }
+}

reports/programAcceptance.md

@@ -0,0 +1,35 @@
+# v0.28 通用工程验收
+
+本轮新增 `project new/generate/check`，默认生成普通 Go 程序，不包含 API、网络监听、外部服务初始化或业务任务。项目维护配置、svc 和 Run；模板维护入口、加载与生命周期装配。
+
+## 发布前回归
+
+2026-09-29，macOS arm64，Go 1.27.1 / Go 1.22.12：
+
+- `GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -count=1 ./...`：56 个测试包通过，含现有 API 生成消费者与新通用工程消费者。
+- `GOTOOLCHAIN=go1.22.12 GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -count=1 ./...`：56 个测试包通过。
+- `go vet ./...`、`go build ./...`、`git diff --check`：通过。
+- 最终补充真实进程异常退出断言后，新生成器再次通过 race 集成回归与 Go 1.22 集成回归。
+- `examples/program` 在临时副本中使用显式本地替换，完成 tidy、race、配置检查、实际一次性运行、生成漂移检查；仓库示例不含本地 replace。
+
+## 验证边界
+
+生成保护覆盖：手写文件逐字节保留、修改生成文件报冲突、缺失生成文件补回、缺失手写文件显式报错、只读 check/预览、模板升级漂移、工程与模块身份、最低依赖版本、路径/符号链接和锁保护、写入冲突后的事务回滚。
+
+实际生成的消费者保留全部入口/加载/装配代码，只修改项目所有文件，覆盖：
+
+- 一次性正常完成，主流程 defer 结束后反序关闭资源。
+- Init 返回错误或 panic，Run 返回错误、panic、Goexit，以及组件报告致命故障。
+- 初始化到一半失败后停止并等待已经启动的工作。
+- 停止接收后等待处理与确认完成，期间 WorkContext 仍可用。
+- 排空超时后请求取消，宽限期内完成则可清理；仍未结束则保留共享资源和日志。
+- 主运行入口、后台工作、失败初始化后的工作不响应取消，均不会提前关闭资源。
+- 显式环境引用、固定值不被隐式覆盖、非法配置阻止初始化，check-config 不打开日志文件。
+- 真实构建的进程：SIGINT/SIGTERM 正常退出码 0；Run 错误/panic、主流程不响应停止导致超时，退出码 1。
+- 默认进程通过本机 lsof 检查，无 TCP/UDP 端口；生成目录和源码无 API/Handler/Swagger/数据库/队列启动。
+
+文件替换只对单文件原子，普通失败会回滚，整个工程不具备崩溃事务性。未登记的 goroutine、不遵守完成契约的项目组件、SIGKILL 和进程崩溃无法由模板保证收尾。新模板不改变既有调度器或队列的重试/投递语义。
+
+## 远程发布验收
+
+发布后运行 `scripts/verifyProgramRelease.py` 与原有 `scripts/verifyManagedRelease.py`，使用空模块缓存安装固定远程 CLI，禁止本地 replace。结果在完成后补入本文件及 JSON 报告。

scripts/verifyProgramRelease.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Verify the generic project CLI and its consumer from a fresh remote module cache."""
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import tempfile
+import time
+
+from verifyErrorInheritanceRelease import run
+
+ROOT = Path(__file__).resolve().parents[1]
+MODULE = "git.yuntuo.hk/k2safe/go-omni"
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--version", required=True)
+    parser.add_argument("--report", type=Path, default=ROOT / "reports/programRemote.json")
+    args = parser.parse_args()
+    if not re.fullmatch(r"v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?", args.version):
+        parser.error("a fixed release version is required")
+    env = {k: v for k, v in os.environ.items() if not k.startswith("GO_OMNI_")}
+    env.update(GOWORK="off", GOFLAGS="", GOPRIVATE="git.yuntuo.hk", GONOSUMDB="git.yuntuo.hk")
+    started = time.monotonic()
+    with tempfile.TemporaryDirectory(prefix="goOmniProgramRelease-") as directory:
+        temp = Path(directory)
+        (temp / "bin").mkdir()
+        env.update(GOBIN=str(temp / "bin"), GOMODCACHE=str(temp / "modcache"))
+        print(f"Installing remote CLI {args.version} with an empty module cache", flush=True)
+        run(["go", "install", MODULE + "/cmd/go-omni@" + args.version], temp, env)
+        cli = temp / "bin/go-omni"
+        # No version argument and no local replacement: installed CLI owns the default.
+        starter = temp / "program"
+        run([cli, "project", "new", starter, "--module", "example.com/released"], temp, env)
+        run(["go", "mod", "tidy"], starter, env)
+        dependency = json.loads(run(["go", "list", "-m", "-json", MODULE], starter, env))
+        assert dependency["Version"] == args.version and dependency.get("Sum") and not dependency.get("Replace")
+        downloaded = Path(dependency["Dir"])
+        env.update(GO_OMNI_SCAFFOLD_INTEGRATION="1", GO_OMNI_RELEASE_CLI=str(cli), GO_OMNI_RELEASE_VERSION=args.version)
+        print("Testing downloaded generator, shared file transaction and generated program lifecycle", flush=True)
+        output = run(["go", "test", "-race", "-count=1", "-json", "-timeout=240s",
+                      "./cmd/go-omni/projectgen", "./cmd/go-omni/internal/genfs"], downloaded, env)
+        events = [json.loads(line) for line in output.splitlines() if line.startswith("{")]
+        passed = [e["Test"] for e in events if e.get("Action") == "pass" and "Test" in e]
+        assert "TestGeneratedProgramConsumer" in passed and "TestConflictRollsBackEarlierWrites" in passed, output
+        assert not any(e.get("Action") == "fail" for e in events), output
+        evidence = "".join(e.get("Output", "") for e in events)
+        assert "no local replace" in evidence, evidence
+        # Check the committed standalone example with only project-owned additions.
+        for name in ("internal/config/config.go", "internal/run/run.go", "etc/config.yaml"):
+            text = (ROOT / "examples/program" / name).read_text().replace("example.com/program", "example.com/released")
+            (starter / name).write_text(text)
+        run([cli, "project", "check"], starter, env)
+        run(["go", "run", ".", "-check-config"], starter, env)
+        example_output = run(["go", "run", "."], starter, env)
+        assert "program.completed" in example_output, example_output
+        run(["go", "test", "./..."], starter, env)
+        sources = list((ROOT / "cmd/go-omni/projectgen").rglob("*.go"))
+        sources += list((ROOT / "cmd/go-omni/projectgen/templates").glob("*.tmpl"))
+        sources += list((ROOT / "cmd/go-omni/internal/genfs").glob("*.go"))
+        sources += [ROOT / "cmd/go-omni/project.go", ROOT / "scripts/verifyProgramRelease.py"]
+        report = {
+            "passed": True, "frameworkVersion": args.version, "frameworkSum": dependency["Sum"],
+            "freshModuleCache": True, "noLocalReplace": True,
+            "durationSeconds": round(time.monotonic() - started, 2), "tests": passed,
+            "checks": ["remoteCLIInstall", "installedVersionDefault", "generatedConsumerBuildRaceVet",
+                       "defaultNoAPIFiles", "defaultNoNetworkListener", "finiteProgram", "SIGINT", "SIGTERM",
+                       "initializationFailureAndPanic", "runErrorPanicGoexit", "fatalComponentFailure",
+                       "nonzeroProcessFailureAndTimeoutExits", "partialStartupDraining", "acknowledgementBeforeResourceClose", "workContextSurvivesGracefulStop",
+                       "cancellationGrace", "unresponsiveRunAndBackgroundWork", "retainedResourcesAndLogger",
+                       "explicitConfigurationOnly", "checkConfigWithoutDependencies", "handwrittenFilesPreserved",
+                       "generatedFileConflict", "missingGeneratedFileRestored", "missingHandwrittenFileNotRecreated",
+                       "readOnlyCheckAndDryRun", "templateDriftUpgrade", "manifestIdentityAndVersionGuards",
+                       "symlinkAndLockProtection", "fileTransactionRollback", "publishedExampleFiniteRun"],
+            "sourceHashes": {str(p.relative_to(ROOT)): hashlib.sha256(p.read_bytes()).hexdigest() for p in sorted(sources)},
+        }
+    args.report.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n")
+    print(f"PASS remote generic program release {args.version}: {len(report['checks'])} checks", flush=True)
+
+
+if __name__ == "__main__":
+    main()