@h-ai/cli 0.1.0-alpha.65 → 0.1.0-alpha.67

package/templates/apps/fullstack/apps/{{projectName}}-app/index.html.hbs

@@ -6,6 +6,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
     <meta name="theme-color" content="#2563eb" />
+    <script src="/runtime-config.js"></script>
     <title>{{html fullstack.appName}}</title>
     <link
       rel="icon"

package/templates/apps/fullstack/apps/{{projectName}}-app/package.json.hbs

@@ -13,9 +13,7 @@
     "dev:prod": "vite --mode prod",
     "dev": "vite dev --host 127.0.0.1 --port {{fullstack.ports.app}}",
     "build": "pnpm paraglide:compile && vite build",
-    "build:prod": "pnpm paraglide:compile && vite build --mode prod",
     "package": "pnpm cap:sync",
-    "deploy": "pnpm package",
     "preview": "vite preview --host 127.0.0.1 --port {{fullstack.ports.app}} --strictPort",
     "check": "pnpm typecheck",
     "typecheck": "pnpm paraglide:compile && svelte-check --tsconfig ./tsconfig.json",

package/templates/apps/fullstack/apps/{{projectName}}-app/public/runtime-config.js.hbs

@@ -0,0 +1,4 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.app}}
+globalThis.__HAI_PUBLIC_CONFIG__ = {}
+{{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-app/vite.config.ts.hbs

@@ -11,8 +11,8 @@ import { defineConfig } from 'vitest/config'
 
 const envDir = fileURLToPath(new URL('../../', import.meta.url))
 
-export default defineConfig(({ mode }) => {
-  const envResult = core.config.loadEnvFiles({ mode, envDir })
+export default defineConfig(({ mode, command }) => {
+  const envResult = command === 'build' ? { success: true as const, data: {} as Record<string, string> } : core.config.loadEnvFiles({ mode, envDir })
   if (!envResult.success)
     throw new Error(envResult.error.message)
   const env = envResult.data
@@ -51,7 +51,7 @@ export default defineConfig(({ mode }) => {
     },
     envPrefix: ['VITE_', 'PUBLIC_'],
     ssr: {
-      noExternal: [/@h-ai\//, /{{fullstack.sharedPackageName}}/],
+      noExternal: ['@h-ai/ui', /{{fullstack.sharedPackageName}}/],
     },
     test: {
       environment: 'node',

package/templates/apps/fullstack/apps/{{projectName}}-desktop/README.md.hbs

@@ -2,9 +2,19 @@
 {{#if fullstack.frontends.desktop}}
 # {{projectName}}-desktop
 
+## 简介
+
 桌面端工程，参考 `apps/desktop-app` 使用 Tauri v2 + Svelte 5 + Vite，前端通过共享 contract 调用 `{{fullstack.servPackageName}}`。
 
-## i18n 与 shared 协同
+## 核心功能清单
+
+- Tauri v2 桌面壳与共享管理界面。
+- 运行时配置 API 地址，无需按环境重复打包。
+- 原生令牌仅存内存，重启后重新登录。
+
+## 使用入门
+
+### i18n 与 shared 协同
 
 - 本端页面文案：`messages/{locale}.json` + `project.inlang/settings.json`
 - 共享 Shell/主题/语言/API：`packages/{{fullstack.sharedPackageName}}`
@@ -14,7 +24,7 @@
 
 自定义建议：桌面端菜单、状态、快捷操作文案放在本目录 `messages/`；跨端通用能力放到 shared。
 
-## 编译、打包与部署
+### 编译、打包与部署
 
 ```bash
 # 仅前端开发，默认端口 {{fullstack.ports.desktop}}
@@ -26,22 +36,27 @@ pnpm --filter {{projectName}}-desktop tauri:dev
 # 编译 WebView 前端产物到 dist/
 pnpm --filter {{projectName}}-desktop build
 
-# 打包桌面安装包
-pnpm --filter {{projectName}}-desktop package
-
-# 当前模板的 deploy 入口默认执行 package，可按发布平台替换
-pnpm --filter {{projectName}}-desktop deploy
+# 在工程根打包桌面安装包；在对应系统构建 windows / linux / macos
+pnpm build --target desktop --platform windows --arch x64
 ```
 
-打包前需要安装 Rust 工具链和 Tauri 平台依赖。生产环境部署时同步调整 `.env` 中的 `PUBLIC_API_BASE` 与 `src-tauri/tauri.conf.json` 的 `connect-src` 白名单。
+打包前需要安装 Rust 工具链和 Tauri 平台依赖。构建不读取 .env.prod/.env.local；启动已安装程序前设置进程 PUBLIC_API_BASE（HTTP(S)，不含凭据、查询和片段）。Rust 会在页面加载前注入公开地址，仅将该 Origin 加入 CSP；不需要为 test/prod 重打安装包。缺省连接 http://localhost:3000/api/v1。
 
-## IAM 认证配置
+### IAM 认证配置
 
-服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。所有节点共享同一 DB 与 Redis；Memory 仅用于单进程。
+服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。单实例可使用 Memory；多实例需共享数据库与 Redis，并按工程根 README 配置写入路由和传输会话。
 
 LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IAM 服务端 workspace 安装 ldapts，再配置 login.ldap 与连接信息。自定义 onOtpSendEmail/onOtpSendSms/onPasswordResetRequest 回调可独立于 Reach 使用，投递失败须拒绝 Promise。协议在 Modal 显示；LoginForm/RegisterForm 提供 header/extraFields/footer，AuthPanel 透传 loginHeader/loginFields/loginFooter 和 registerHeader/registerFields/registerFooter。配置及例子见生成项目的 hai-iam/hai-ui skills。
 
 协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
 
 完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
+
+## 开发测试
+
+从工程根执行 `pnpm typecheck`、`pnpm lint`、`pnpm build`、`pnpm test` 和 `pnpm test:e2e`。浏览器预览通过后，原生壳仍需在对应系统或设备单独验收。
+
+## 许可证
+
+Apache-2.0
 {{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-desktop/package.json.hbs

@@ -12,10 +12,9 @@
     "dev:test": "vite --mode test",
     "dev:prod": "vite --mode prod",
     "dev": "vite dev --host 127.0.0.1 --port {{fullstack.ports.desktop}}",
-    "build": "pnpm paraglide:compile && vite build",
-    "build:prod": "pnpm paraglide:compile && vite build --mode prod",
+    "compile": "pnpm paraglide:compile && vite build",
+    "build": "pnpm compile",
     "package": "pnpm tauri:build",
-    "deploy": "pnpm package",
     "preview": "vite preview --host 127.0.0.1 --port {{fullstack.ports.desktop}} --strictPort",
     "check": "pnpm typecheck",
     "typecheck": "pnpm paraglide:compile && svelte-check --tsconfig ./tsconfig.json",

package/templates/apps/fullstack/apps/{{projectName}}-desktop/src-tauri/src/lib.rs.hbs

@@ -1,16 +1,87 @@
 {{! @skipIfEmpty }}
 {{#if fullstack.frontends.desktop}}
+use std::collections::HashMap;
+use tauri::utils::config::{Csp, CspDirectiveSources};
+
+/// 校验运行期 API 地址；例如 `https://api.example.test/api/v1`，不接收认证信息或查询参数。
+fn parse_runtime_api(value: &str) -> Result<tauri::Url, &'static str> {
+    let url = tauri::Url::parse(value).map_err(|_| "Invalid PUBLIC_API_BASE")?;
+    if !["http", "https"].contains(&url.scheme())
+        || url.host_str().is_none()
+        || !url.username().is_empty()
+        || url.password().is_some()
+        || url.query().is_some()
+        || url.fragment().is_some()
+    {
+        return Err(
+            "PUBLIC_API_BASE must be an HTTP(S) URL without credentials, query or fragment",
+        );
+    }
+    Ok(url)
+}
+
+/// 仅将当前运行期 API 的 origin 加入 CSP；不放宽到所有 HTTP/HTTPS 站点。
+fn runtime_csp(policy: Csp, origin: &str) -> Csp {
+    let mut directives: HashMap<String, CspDirectiveSources> = policy.into();
+    for name in ["connect-src", "img-src"] {
+        directives.entry(name.to_string()).or_default().push(origin);
+    }
+    directives.into()
+}
+
 #[tauri::command]
 fn greet(name: &str) -> String {
-    format!("Hello, {}! Welcome to {{projectName}} Desktop.", name)
+    format!("Hello, {}! Welcome to Desktop.", name)
 }
 
 #[cfg_attr(mobile, tauri::mobile_entry_point)]
 pub fn run() {
+    // 构建不读取部署环境；启动时从进程 PUBLIC_API_BASE 获取公开地址。
+    let api = parse_runtime_api(
+        &std::env::var("PUBLIC_API_BASE")
+            .unwrap_or_else(|_| "http://localhost:3000/api/v1".to_string()),
+    )
+    .expect("Invalid runtime API configuration");
+    let mut context = tauri::generate_context!();
+    if let Some(policy) = context.config_mut().app.security.csp.take() {
+        context.config_mut().app.security.csp =
+            Some(runtime_csp(policy, &api.origin().ascii_serialization()));
+    }
+    let script = format!(
+        "globalThis.__HAI_PUBLIC_CONFIG__={};",
+        serde_json::json!({ "apiBase": api.as_str() })
+    );
     tauri::Builder::default()
         .plugin(tauri_plugin_shell::init())
+        .append_invoke_initialization_script(script)
         .invoke_handler(tauri::generate_handler![greet])
-        .run(tauri::generate_context!())
+        .run(context)
         .expect("error while running tauri application");
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn validates_runtime_address_and_scopes_csp() {
+        let api = parse_runtime_api("https://api.example.test:8443/custom/v2").unwrap();
+        let policy = runtime_csp(
+            Csp::Policy("default-src 'self'; connect-src 'self'".into()),
+            &api.origin().ascii_serialization(),
+        );
+        let directives: HashMap<String, CspDirectiveSources> = policy.into();
+        let sources: Vec<String> = directives["connect-src"].clone().into();
+        assert!(sources.contains(&"https://api.example.test:8443".to_string()));
+        assert!(!sources.contains(&"https:".to_string()));
+        for value in [
+            "file:///tmp/config",
+            "https://user:secret@host",
+            "https://host/?token=secret",
+            "relative",
+        ] {
+            assert!(parse_runtime_api(value).is_err());
+        }
+    }
+}
 {{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-desktop/src-tauri/tauri.conf.json.hbs

@@ -3,11 +3,11 @@
 {
   "$schema": "https://schema.tauri.app/config/2",
   "productName": {{json fullstack.appName}},
-  "version": "0.1.0",
+  "version": "../../../package.json",
   "identifier": "com.hai.{{fullstack.nativeAppIdSegment}}.desktop",
   "build": {
     "beforeDevCommand": "pnpm dev",
-    "beforeBuildCommand": "pnpm build",
+    "beforeBuildCommand": "pnpm compile",
     "devUrl": "http://localhost:{{fullstack.ports.desktop}}",
     "frontendDist": "../dist"
   },

package/templates/apps/fullstack/apps/{{projectName}}-desktop/vite.config.ts.hbs

@@ -12,8 +12,8 @@ import { defineConfig } from 'vitest/config'
 const host = process.env.TAURI_DEV_HOST
 const envDir = fileURLToPath(new URL('../../', import.meta.url))
 
-export default defineConfig(({ mode }) => {
-  const envResult = core.config.loadEnvFiles({ mode, envDir })
+export default defineConfig(({ mode, command }) => {
+  const envResult = command === 'build' ? { success: true as const, data: {} as Record<string, string> } : core.config.loadEnvFiles({ mode, envDir })
   if (!envResult.success)
     throw new Error(envResult.error.message)
   const env = envResult.data

package/templates/apps/fullstack/apps/{{projectName}}-miniapp/README.md.hbs

@@ -2,14 +2,24 @@
 {{#if fullstack.hasMiniapp}}
 # {{projectName}}-miniapp
 
-小程序端当前为预留占位，不参与 workspace 构建、单元测试或 E2E，但已预置 inlang 标准目录：
+## 简介
 
-- `project.inlang/settings.json`：小程序端 locale 配置
-- `messages/zh-CN.json`、`messages/en-US.json`：小程序端自有文案
+小程序预留目录，目前没有可运行的小程序应用。
 
-消息格式插件复用 workspace 已安装的依赖，从根目录 `node_modules` 加载；生成后先在 workspace 根目录安装依赖，无需从 CDN 加载插件。
+## 核心功能清单
 
-后续实现时建议复用 `packages/{{fullstack.contractPackageName}}` 中的 Schema 与路径常量，保持接口真相源一致。
+- 已提供 `project.inlang/settings.json` 与中英文 `messages/`。
+- 可复用 `packages/{{fullstack.contractPackageName}}` 的接口类型。
 
-协同边界：跨端通用文案/组件放 `packages/{{fullstack.sharedPackageName}}`，小程序独有页面文案放本目录 `messages/`。
+## 使用入门
+
+选定小程序框架后再实现页面、请求适配和认证。小程序文案放本目录 `messages/`，跨端通用内容放 `packages/{{fullstack.sharedPackageName}}`；消息格式插件使用工程根已安装的依赖。
+
+## 开发测试
+
+本目录不参与 workspace 构建、单元测试或 E2E。接入实际框架后增加对应命令，并在目标平台验证登录、请求、导航与发布包。
+
+## 许可证
+
+Apache-2.0
 {{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-web/README.md.hbs

@@ -2,9 +2,19 @@
 {{#if fullstack.frontends.web}}
 # {{projectName}}-web
 
+## 简介
+
 响应式 mini 后台 Web 前端，通过 `packages/{{fullstack.sharedPackageName}}` 调用后端 API，并通过 `@h-ai/ui` 组件搭建页面。
 
-## i18n 与 shared 协同
+## 核心功能清单
+
+- 浏览器访问共享管理界面与个人设置。
+- 与 API 共用接口类型、登录状态、主题和语言。
+- 可单独构建 Web 镜像并增量更新。
+
+## 使用入门
+
+### i18n 与 shared 协同
 
 - 本端页面文案：`messages/{locale}.json` + `project.inlang/settings.json`
 - 共享 Shell/主题/语言/API：`packages/{{fullstack.sharedPackageName}}`
@@ -12,7 +22,7 @@
 
 自定义建议：Web 独有文案放在本目录 `messages/`；跨端通用文案或组件放到 shared。
 
-## 编译、打包与部署
+### 编译、打包与部署
 
 ```bash
 # 开发预览，默认端口 {{fullstack.ports.web}}
@@ -20,21 +30,25 @@ pnpm --filter {{projectName}}-web dev
 
 # 编译 Web 前端
 pnpm --filter {{projectName}}-web build
-
-# 打包部署产物；默认等同 build，可按目标平台替换
-pnpm --filter {{projectName}}-web package
-
-# 当前模板的 deploy 入口默认执行 package，可替换为 CDN / 容器发布脚本
-pnpm --filter {{projectName}}-web deploy
 ```
 
-## IAM 认证配置
+从工程根运行 `pnpm build --target docker` 导出镜像。默认带部署工具，可运行 `pnpm run deploy --env test --build` 一次完成构建发布，或 `pnpm run deploy --env prod --bundle-only` 交付已有镜像及跨平台脚本。完整包包含自建中间件，人工部署与按服务更新见工程根 README。
 
-服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。所有节点共享同一 DB 与 Redis；Memory 仅用于单进程。
+### IAM 认证配置
+
+服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。单实例可使用 Memory；多实例需共享数据库与 Redis，并按工程根 README 配置写入路由和传输会话。
 
 LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IAM 服务端 workspace 安装 ldapts，再配置 login.ldap 与连接信息。自定义 onOtpSendEmail/onOtpSendSms/onPasswordResetRequest 回调可独立于 Reach 使用，投递失败须拒绝 Promise。协议在 Modal 显示；LoginForm/RegisterForm 提供 header/extraFields/footer，AuthPanel 透传 loginHeader/loginFields/loginFooter 和 registerHeader/registerFields/registerFooter。配置及例子见生成项目的 hai-iam/hai-ui skills。
 
 协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
 
 完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
+
+## 开发测试
+
+从工程根执行 `pnpm typecheck`、`pnpm lint`、`pnpm build`、`pnpm test` 和 `pnpm test:e2e`。浏览器预览通过后，原生壳仍需在对应系统或设备单独验收。
+
+## 许可证
+
+Apache-2.0
 {{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-web/package.json.hbs

@@ -13,9 +13,7 @@
     "dev:prod": "vite --mode prod",
     "dev": "vite dev --host 127.0.0.1 --port {{fullstack.ports.web}}",
     "build": "pnpm paraglide:compile && vite build",
-    "build:prod": "pnpm paraglide:compile && vite build --mode prod",
     "package": "pnpm build",
-    "deploy": "pnpm package",
     "preview": "vite preview --host 127.0.0.1 --port {{fullstack.ports.web}} --strictPort",
     "check": "pnpm typecheck",
     "typecheck": "pnpm paraglide:compile && svelte-check --tsconfig ./tsconfig.json",

package/templates/apps/fullstack/apps/{{projectName}}-web/vite.config.ts.hbs

@@ -11,8 +11,8 @@ import { defineConfig } from 'vitest/config'
 
 const envDir = fileURLToPath(new URL('../../', import.meta.url))
 
-export default defineConfig(({ mode }) => {
-  const envResult = core.config.loadEnvFiles({ mode, envDir })
+export default defineConfig(({ mode, command }) => {
+  const envResult = command === 'build' ? { success: true as const, data: {} as Record<string, string> } : core.config.loadEnvFiles({ mode, envDir })
   if (!envResult.success)
     throw new Error(envResult.error.message)
   const env = envResult.data
@@ -51,7 +51,7 @@ export default defineConfig(({ mode }) => {
     },
     envPrefix: ['VITE_', 'PUBLIC_'],
     ssr: {
-      noExternal: [/@h-ai\//, /{{fullstack.sharedPackageName}}/],
+      noExternal: ['@h-ai/ui', /{{fullstack.sharedPackageName}}/],
     },
     test: {
       environment: 'node',

package/templates/apps/fullstack/e2e/fullstack.spec.ts.hbs

@@ -61,7 +61,7 @@ test('service rejects plaintext business requests', async ({ request }) => {
 })
 
 {{#if fullstack.e2eFrontend}}
-test('hash routing restores direct links, refresh and browser history', async ({ page }) => {
+test('hash routing and responsive workspace preserve usable content width', async ({ page }, testInfo) => {
   await page.goto('/#/roles?source=direct')
   await login(page, 'admin', adminPassword)
   await expect(page.getByTestId('roles-page')).toBeVisible()
@@ -70,6 +70,16 @@ test('hash routing restores direct links, refresh and browser history', async ({
   await expect(page.getByTestId('roles-page')).toBeVisible()
   await expect(page.locator('header')).toBeVisible()
   await expect(page.locator('footer')).toBeVisible()
+  for (const width of [1440, 1920, 2560, 3840, 390]) {
+    await page.setViewportSize({ width, height: 960 })
+    expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
+    const main = await page.locator('main').boundingBox()
+    const content = await page.getByTestId('roles-page').boundingBox()
+    expect(content!.width).toBeGreaterThan(main!.width - 80)
+    if (width === 1920)
+      await capture(page, '{{projectName}}-wide.png', testInfo.outputPath('wide-1920.png'))
+  }
+  await page.setViewportSize({ width: 1440, height: 960 })
   await page.getByTestId('nav-settings').click()
   await expect(page).toHaveURL(/#\/settings$/)
   await page.goBack()
@@ -96,6 +106,7 @@ test('branded authentication, profile layout and blur validation work across scr
   await capture(page, '{{projectName}}-register-mobile.png', testInfo.outputPath('register-mobile.png'))
   expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
   await page.reload()
+  await expect(page.getByTestId('login-form')).toBeVisible()
   await capture(page, '{{projectName}}-login-mobile.png', testInfo.outputPath('login-mobile.png'))
   await page.setViewportSize({ width: 1440, height: 960 })
   await login(page, 'admin', adminPassword)

package/templates/apps/fullstack/hai.build.json.hbs

@@ -0,0 +1,7 @@
+{
+  "images": [
+    { "name": "app", "dockerfile": "images/app.Dockerfile", "containerPort": 3000 }{{#if fullstack.frontends.web}},
+    { "name": "web", "dockerfile": "images/web.Dockerfile", "containerPort": 8080 }{{/if}}
+  ]{{#if fullstack.frontends.desktop}},
+  "desktop": ["apps/{{projectName}}-desktop"]{{/if}}
+}

package/templates/apps/fullstack/images/app.Dockerfile.hbs

@@ -0,0 +1,36 @@
+FROM node:24.22.1-bookworm-slim AS build
+ARG SQLITE_PREBUILD_MIRROR=
+ENV npm_config_better_sqlite3_binary_host_mirror=$SQLITE_PREBUILD_MIRROR
+
+ENV PNPM_HOME=/pnpm
+ENV PATH=$PNPM_HOME:$PATH
+ENV CI=true
+ENV ONNXRUNTIME_NODE_INSTALL_CUDA=skip
+WORKDIR /workspace
+
+RUN corepack enable && corepack prepare pnpm@12.11.2 --activate && pnpm config set store-dir /pnpm/store
+COPY pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY images/dependencies/ ./
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm fetch --ignore-scripts
+COPY . .
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm install --offline --frozen-lockfile --ignore-scripts
+RUN pnpm --filter {{fullstack.servPackageName}}... --if-present build
+
+RUN --mount=type=cache,id={{projectName}}-sqlite,target=/root/.npm/_prebuilds if [ -d node_modules/better-sqlite3 ]; then cd node_modules/better-sqlite3; for attempt in 1 2 3; do node -e "require('node:child_process').execFileSync(process.execPath,[require.resolve('prebuild-install/bin.js'),'--verbose'],{stdio:'inherit'})" && break; [ "$attempt" = 3 ] && exit 1; sleep 3; done; fi
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store --mount=type=cache,id={{projectName}}-sqlite,target=/root/.npm/_prebuilds pnpm pm deploy --filter {{fullstack.servPackageName}} --prod /prod/service
+
+FROM node:24.22.1-bookworm-slim AS service
+
+ENV NODE_ENV=production
+ENV HOST=0.0.0.0
+ENV PORT=3000
+WORKDIR /app
+
+COPY --from=build --chown=node:node /prod/service ./
+RUN mkdir -p /app/data && chown node:node /app/data
+
+USER node
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+  CMD node -e "fetch('http://127.0.0.1:'+process.env.PORT+'/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+CMD ["node", "dist/index.js"]

package/templates/apps/fullstack/images/web.Dockerfile.hbs

@@ -0,0 +1,34 @@
+{{#if fullstack.frontends.web}}
+FROM node:24.22.1-bookworm-slim AS build
+ARG SQLITE_PREBUILD_MIRROR=
+ENV npm_config_better_sqlite3_binary_host_mirror=$SQLITE_PREBUILD_MIRROR
+
+ENV PNPM_HOME=/pnpm
+ENV PATH=$PNPM_HOME:$PATH
+ENV CI=true
+WORKDIR /workspace
+
+RUN corepack enable && corepack prepare pnpm@12.11.2 --activate && pnpm config set store-dir /pnpm/store
+COPY pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY images/dependencies/ ./
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm fetch --ignore-scripts
+COPY . .
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm install --offline --frozen-lockfile --ignore-scripts
+RUN pnpm --filter {{fullstack.sharedPackageName}} paraglide:compile && pnpm --filter {{projectName}}-web... --if-present build
+
+FROM nginxinc/nginx-unprivileged:1.29.8-alpine AS web
+
+ENV PUBLIC_API_BASE=
+ENV NGINX_ENVSUBST_FILTER=PUBLIC_API_BASE_BASE64
+ENV NGINX_ENVSUBST_OUTPUT_DIR=/tmp/hai-runtime-config
+
+RUN mkdir -p /tmp/hai-runtime-config
+COPY images/web/nginx.conf /etc/nginx/conf.d/default.conf
+COPY --chmod=755 images/web/19-runtime-config.envsh /docker-entrypoint.d/19-runtime-config.envsh
+COPY images/web/runtime-config.js.template /etc/nginx/templates/runtime-config.js.template
+COPY --from=build /workspace/apps/{{projectName}}-web/dist /usr/share/nginx/html
+
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget -Y off -q -O /dev/null http://127.0.0.1:8080/health || exit 1
+{{/if}}

package/templates/apps/fullstack/package.json.hbs

@@ -15,24 +15,18 @@
     "start:prod": "pnpm --filter {{fullstack.servPackageName}} start:prod",
     "dev:test": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm --parallel --filter {{fullstack.servPackageName}}{{#each fullstack.frontendApps}} --filter {{packageName}}{{/each}} dev:test",
     "dev:prod": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm --parallel --filter {{fullstack.servPackageName}}{{#each fullstack.frontendApps}} --filter {{packageName}}{{/each}} dev:prod",
-    "build:prod": "pnpm build && pnpm -r --if-present build:prod",
-    "compile": "pnpm typecheck && pnpm build",
-    "build": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm -r --if-present build",
-    "docker:build": "docker build --target runtime -t {{projectName}}:latest .",
-    "docker:build:data": "docker build --target runtime-with-data --build-context embedded-data=./packages/{{projectName}}-serv/data -t {{projectName}}:latest ."{{#if fullstack.frontends.web}},
-    "docker:build:web": "docker build --target web -t {{projectName}}-web:latest ."{{/if}},
-    "podman:build": "podman build --format docker --jobs=1 --target runtime -t {{projectName}}:latest .",
-    "podman:build:data": "podman build --format docker --jobs=1 --target runtime-with-data --build-context embedded-data=./packages/{{projectName}}-serv/data -t {{projectName}}:latest ."{{#if fullstack.frontends.web}},
-    "podman:build:web": "podman build --format docker --jobs=1 --target web -t {{projectName}}-web:latest ."{{/if}},
-    "package": "pnpm build{{#if fullstack.frontends.web}} && pnpm --filter {{projectName}}-web package{{/if}}{{#if fullstack.frontends.app}} && pnpm --filter {{projectName}}-app package{{/if}}{{#if fullstack.frontends.desktop}} && pnpm --filter {{projectName}}-desktop package{{/if}}",
-    "deploy": "pnpm package",
+    "compile": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm -r --if-present build",
+    "build": "hai build",
+{{#if features.deploy}}
+    "deploy": "hai deploy packages/{{projectName}}-serv",
+{{/if}}
     "check": "pnpm typecheck",
     "typecheck": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm -r --if-present typecheck",
     "lint": "eslint *.js *.ts e2e && pnpm -r --if-present lint",
     "lint:fix": "eslint *.js *.ts e2e --fix && pnpm -r --if-present lint:fix",
     "test": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm -r --if-present test",
     "test:watch": "pnpm -r --parallel --if-present test:watch",
-    "test:e2e": "pnpm build && playwright test",
+    "test:e2e": "pnpm compile && node scripts/run-e2e.mjs",
     "clean": "pnpm -r --if-present clean && rimraf node_modules .turbo"
   },
   "dependencies": {
@@ -41,6 +35,7 @@
     "{{fullstack.sharedPackageName}}": "workspace:*"
   },
   "devDependencies": {
+    "@h-ai/cli": "{{haiPackageSpecifier}}",
 {{#if features.deploy}}
     "@h-ai/deploy": "{{haiPackageSpecifier}}",
 {{/if}}

package/templates/apps/fullstack/packages/{{projectName}}-contract/README.md.hbs

@@ -1,8 +1,18 @@
 # {{fullstack.contractPackageName}}
 
+## 简介
+
 共享 API 契约包，包含 Zod Schema、`apiContract.route()` 业务接口定义与工程级 contract。业务 schema、角色、流程及限额是模板初始方案，按用户需求修改，并同步服务端授权、调用方、测试与说明；不要求需求沿用默认业务。
 
-## 骨架说明
+## 核心功能清单
+
+- 共享接口路径、输入输出 Schema 和类型。
+- 客户端与服务端使用同一份 contract。
+- 不包含服务端业务实现，也不加载私有配置。
+
+## 使用入门
+
+### 骨架说明
 
 - `src/app-schemas.ts`：跨接口、跨层复用的输入/数据 Schema 与类型。
 - `src/app-contract.ts`：app 领域 contract；每个业务 path 直接写在对应接口定义中。
@@ -13,7 +23,18 @@
 API 前缀、健康检查与跨端 Header 等传输配置位于 serv 包的 `config/_serv.yml`。
 `SUPPORTED_LOCALES` 为生成时实际编译的语言列表；`app.info` 中名称、版本、环境、默认语言来自后端 core 配置。更新公开契约时同时更新 serv、shared typed API client、各端 UI 与测试。
 
-## 开发
+### 开发
 
 - `pnpm --filter {{fullstack.contractPackageName}} typecheck`
 - `pnpm --filter {{fullstack.contractPackageName}} test`
+
+## 开发测试
+
+```sh
+pnpm --filter {{fullstack.contractPackageName}} typecheck
+pnpm --filter {{fullstack.contractPackageName}} test
+```
+
+## 许可证
+
+Apache-2.0

package/templates/apps/fullstack/packages/{{projectName}}-serv/README.md.hbs

@@ -1,8 +1,18 @@
 # {{fullstack.servPackageName}}
 
+## 简介
+
 后端 API Service，基于 `@h-ai/serv` 将共享 contract 装配为最小 HTTP App 抽象，不在应用代码中直接暴露 Hono。
 
-## 默认功能与配置
+## 核心功能清单
+
+- HTTP 服务、健康检查和共享 contract 的 procedure 实现。
+- 用户、角色、审计与个人设置的示例业务。
+- 模块配置、加密传输与服务端权限校验。
+
+## 使用入门
+
+### 默认功能与配置
 
 以下是可运行示例的初始实现，角色/权限、管理流程、头像限额、分页、审计策略及部署方案均可按用户需求调整。需求与代码或模板规则不一致时，以需求为业务基线同步实现、测试与过期说明；实际框架 API 契约和服务端安全校验仍需满足。
 
@@ -24,7 +34,7 @@ CLI 已生成根目录 `.env.local`，`HAI_ADMIN_DEFAULT_PASSWORD` 为每个项
 
 业务修改提交后的审计记录采用最大努力策略：写入失败输出包含操作及资源的结构化错误日志，业务仍返回原操作结果，避免将已经完成的变更误报为失败；应用启动时 audit 初始化失败则停止启动。
 
-## 开发
+### 开发
 
 所有配置字段以模块 Schema 为准；未使用字段和替代 Provider 用注释保留。叶子环境变量只覆盖已有 YAML 路径，先取消相应键的注释，或用 `HAI_DB` / `HAI_CACHE` 等整体对象覆盖；`connectTimeout` 对应 `HAI_CACHE_CONNECTTIMEOUT`。凭据示例在根 `.env.example`，实际密钥保存在忽略的 `.env.local` 或部署环境。`.gitignore` 的 `**/data/` 忽略所有运行数据及 `.gitkeep`；运行时会创建目录。`crypto.init()` 无配置参数，datapipe 为纯函数，不提供虚构配置。
 
@@ -33,20 +43,31 @@ CLI 已生成根目录 `.env.local`，`HAI_ADMIN_DEFAULT_PASSWORD` 为每个项
 - `pnpm --filter {{fullstack.servPackageName}} dev`
 - `pnpm --filter {{fullstack.servPackageName}} test`
 
-## 容器运行
+### 容器运行
+
+从工程根运行 `pnpm build --target docker` 导出镜像。默认带部署工具，可运行 `pnpm run deploy --env test --build` 一次完成构建发布，或 `pnpm run deploy --env prod --bundle-only` 交付已有镜像及跨平台脚本。完整包包含自建中间件，人工部署与按服务更新见工程根 README。
 
-- 根目录 `pnpm docker:build` / `pnpm podman:build` 直接生成本服务镜像；Web 使用独立的 `docker:build:web` / `podman:build:web` 镜像。
 - 服务镜像直接由 `@h-ai/serv` 对外监听，配置挂载点为 `/app/config`，数据目录为 `/app/data`，不包含额外转发进程。
 - Web 镜像不烘焙 API 地址；启动时使用 `-e PUBLIC_API_BASE=https://api.example.com` 注入，同一镜像可部署到不同环境。未设置时 Web 默认请求自身 origin。
 - YAML 配置使用 `${ENV_NAME:default}` 接收运行时环境变量；不要把密钥写入镜像。
-- 将 SQLite/本地存储放入本目录 `data/` 后运行 `pnpm docker:build:data` / `pnpm podman:build:data`，可生成带初始数据的镜像，持续写入仍应使用 volume。
 
-## IAM 认证配置
+### IAM 认证配置
 
-服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。所有节点共享同一 DB 与 Redis；Memory 仅用于单进程。
+服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。单实例可使用 Memory；多实例需共享数据库与 Redis，并按工程根 README 配置写入路由和传输会话。
 
 LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IAM 服务端 workspace 安装 ldapts，再配置 login.ldap 与连接信息。自定义 onOtpSendEmail/onOtpSendSms/onPasswordResetRequest 回调可独立于 Reach 使用，投递失败须拒绝 Promise。协议在 Modal 显示；LoginForm/RegisterForm 提供 header/extraFields/footer，AuthPanel 透传 loginHeader/loginFields/loginFooter 和 registerHeader/registerFields/registerFooter。配置及例子见生成项目的 hai-iam/hai-ui skills。
 
 协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
 
 完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
+
+## 开发测试
+
+```sh
+pnpm --filter {{fullstack.servPackageName}} typecheck
+pnpm --filter {{fullstack.servPackageName}} test
+```
+
+## 许可证
+
+Apache-2.0