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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "0.1.0-alpha.63",
+  "version": "0.1.0-alpha.65",
   "description": "Hai Framework CLI for project scaffolding and code generation.",
   "license": "Apache-2.0",
   "keywords": [
@@ -30,7 +30,7 @@
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "dependencies": {
-    "@h-ai/core": "0.1.0-alpha.63",
+    "@h-ai/core": "0.1.0-alpha.65",
     "cac": "^7.0.1",
     "chalk": "^6.0.1",
     "fast-wrap-ansi": "^0.2.2",
@@ -41,11 +41,12 @@
     "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@h-ai/cache": "0.1.0-alpha.63",
-    "@h-ai/deploy": "0.1.0-alpha.63",
-    "@h-ai/reach": "0.1.0-alpha.63",
-    "@h-ai/reldb": "0.1.0-alpha.63",
-    "@h-ai/storage": "0.1.0-alpha.63",
+    "@h-ai/cache": "0.1.0-alpha.65",
+    "@h-ai/crypto": "0.1.0-alpha.65",
+    "@h-ai/deploy": "0.1.0-alpha.65",
+    "@h-ai/reach": "0.1.0-alpha.65",
+    "@h-ai/reldb": "0.1.0-alpha.65",
+    "@h-ai/storage": "0.1.0-alpha.65",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^26.6.5",
     "@types/prompts": "^2.4.9",
@@ -62,6 +63,7 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "test": "vitest run",
+    "test:deploy-gates": "node tests/run-scaffold-gates.mjs --deploy",
     "test:e2e": "pnpm test:scaffold-gates",
     "test:scaffold-gates": "pnpm build && node tests/run-scaffold-gates.mjs",
     "test:watch": "vitest",

package/templates/apps/admin/src/routes/+layout.svelte.hbs

@@ -32,6 +32,8 @@
   <title>{page.data.appConfig.name}</title>
 </svelte:head>
 
-<div class='min-h-screen bg-base-200'>
-  {@render children()}
+<div class='min-h-screen flex flex-col bg-base-200'>
+  <header class='navbar border-b border-base-300 bg-base-100 px-6'><span class='text-lg font-semibold'>{page.data.appConfig.name}</span></header>
+  <div class='flex-1'>{@render children()}</div>
+  <footer class='border-t border-base-300 bg-base-100 p-3 text-center text-xs text-base-content/60'>{page.data.appConfig.name} · {page.data.appConfig.version} · {page.data.appConfig.env}</footer>
 </div>

package/templates/apps/api/.dockerignore.hbs

@@ -12,3 +12,8 @@ playwright-report
 test-results
 **/data
 *.log
+# 仅排除本机私有配置，与 Git 处理一致；公共 .env 与 dev/test/prod 随上下文构建。
+**/.env.local
+**/.env.*.local
+**/.env.runtime
+**/.hai/deploy

package/templates/apps/api/.gitignore.hbs

@@ -5,10 +5,10 @@ dist
 build
 playwright-report
 test-results
-.env
-.env.*
-!.env.example
-!.env.example.hbs
 
 # hai deploy 产物（compose / .env.runtime / 镜像 tar / sidecar 凭据）
 .hai/
+
+# 本机私有配置；公共 .env 与 dev/test/prod 环境文件纳入版本控制。
+.env.local
+.env.*.local

package/templates/apps/api/Dockerfile.hbs

@@ -1,5 +1,11 @@
 # syntax=docker/dockerfile:1.7
 FROM node:24-bookworm-slim AS build
+ARG SQLITE_PREBUILD_MIRROR
+ENV npm_config_better_sqlite3_binary_host_mirror=$SQLITE_PREBUILD_MIRROR
+ARG HAI_DEPLOY_ENVIRONMENT=prod
+ARG HAI_CORE_ENV=production
+ENV HAI_DEPLOY_ENVIRONMENT=$HAI_DEPLOY_ENVIRONMENT
+ENV HAI_CORE_ENV=$HAI_CORE_ENV
 
 ENV PNPM_HOME=/pnpm
 ENV PATH=$PNPM_HOME:$PATH
@@ -12,12 +18,16 @@ RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm fetch
 COPY . .
 RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm install --offline --frozen-lockfile --ignore-scripts
 RUN pnpm build
+RUN 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 pnpm pm deploy --filter {{api.servicePackageName}} --prod /prod/app
 
 FROM node:24-bookworm-slim AS runtime-base
+ARG HAI_DEPLOY_ENVIRONMENT=prod
+ARG HAI_CORE_ENV=production
 
 ENV NODE_ENV=production
-ENV HAI_CORE_ENV=production
+ENV HAI_DEPLOY_ENVIRONMENT=$HAI_DEPLOY_ENVIRONMENT
+ENV HAI_CORE_ENV=$HAI_CORE_ENV
 ENV HOST=0.0.0.0
 ENV PORT=3000
 WORKDIR /app

package/templates/apps/api/apps/{{projectName}}-contract/package.json.hbs

@@ -19,8 +19,10 @@
   ],
   "scripts": {
     "build": "tsup",
+    "check": "pnpm typecheck",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "test": "vitest run",
     "test:watch": "vitest",
     "clean": "rimraf dist .turbo"

package/templates/apps/api/apps/{{projectName}}-service/config/_core.yml.hbs

@@ -4,8 +4,8 @@
 
 name: {{projectName}} API Service
 version: 0.1.0
-env: ${HAI_ENV:development}
-debug: ${HAI_DEBUG:false}
+env: ${HAI_CORE_ENV:development}
+debug: ${HAI_CORE_DEBUG:false}
 
 logging:
   level: info

package/templates/apps/api/apps/{{projectName}}-service/config/_serv.yml.hbs

@@ -18,10 +18,10 @@ http:
   rpc: false
 
 cors:
-  origin: ${HAI_CORS_ORIGIN:*}
-  nativeOrigins: ${HAI_CORS_NATIVEORIGINS:http://localhost,https://tauri.localhost,tauri://localhost,capacitor://localhost}
-{{#if features.iam}}  credentials: ${HAI_CORS_CREDENTIALS:true}
-{{else}}  credentials: ${HAI_CORS_CREDENTIALS:false}
+  origin: ${HAI_SERV_CORS_ORIGIN:*}
+  nativeOrigins: ${HAI_SERV_CORS_NATIVEORIGINS:http://localhost,https://tauri.localhost,tauri://localhost,capacitor://localhost}
+{{#if features.iam}}  credentials: ${HAI_SERV_CORS_CREDENTIALS:true}
+{{else}}  credentials: ${HAI_SERV_CORS_CREDENTIALS:false}
 {{/if}}  allowedHeaders:
     - Authorization
     - Content-Type

package/templates/apps/api/apps/{{projectName}}-service/package.json.hbs

@@ -21,13 +21,20 @@
   ],
   "scripts": {
     "build": "tsup",
+    "build:prod": "pnpm build",
+    "check": "pnpm typecheck",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "test": "vitest run",
     "test:watch": "vitest",
     "clean": "rimraf dist .turbo",
-    "dev": "pnpm build && node dist/index.js",
-    "start": "node dist/index.js"
+    "dev": "pnpm build && node --env-file=.env --env-file=.env.dev --env-file-if-exists=.env.local dist/index.js",
+    "start": "node --env-file=.env --env-file=.env.prod --env-file-if-exists=.env.local dist/index.js",
+    "dev:test": "pnpm build && node --env-file=.env --env-file=.env.test --env-file-if-exists=.env.local dist/index.js",
+    "dev:prod": "pnpm build && pnpm start",
+    "start:test": "node --env-file=.env --env-file=.env.test --env-file-if-exists=.env.local dist/index.js",
+    "start:prod": "pnpm start"
   },
   "dependencies": {
     "@h-ai/core": "{{haiPackageSpecifier}}",

package/templates/apps/api/package.json.hbs

@@ -8,15 +8,24 @@
   "description": "Typed hai API workspace with separated contract and service packages.",
   "scripts": {
     "dev": "pnpm --filter {{api.servicePackageName}} dev",
+    "start": "pnpm --filter {{api.servicePackageName}} start",
+    "start:test": "pnpm --filter {{api.servicePackageName}} start:test",
+    "start:prod": "pnpm --filter {{api.servicePackageName}} start:prod",
+    "dev:test": "pnpm --filter {{api.servicePackageName}} dev:test",
+    "dev:prod": "pnpm --filter {{api.servicePackageName}} dev:prod",
     "compile": "pnpm typecheck && pnpm build",
     "build": "pnpm --filter {{api.contractPackageName}} build && 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=./apps/{{projectName}}-service/data -t {{projectName}}:latest .",
     "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=./apps/{{projectName}}-service/data -t {{projectName}}:latest .",
+    "check": "pnpm typecheck",
     "typecheck": "pnpm --filter {{api.contractPackageName}} build && 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 {{api.contractPackageName}} build && pnpm -r --if-present test",
+    "test:watch": "pnpm -r --parallel --if-present test:watch",
+    "build:prod": "pnpm build",
     "test:e2e": "pnpm build && playwright test",
     "clean": "pnpm -r --if-present clean && rimraf node_modules .turbo"
   },

package/templates/apps/fullstack/.dockerignore.hbs

@@ -6,9 +6,6 @@ Dockerfile
 .codex
 .opencode
 .turbo
-.env
-.env.*
-!.env.example
 **/build
 **/dist
 **/node_modules
@@ -17,3 +14,8 @@ playwright-report
 test-results
 **/data
 *.log
+# 仅排除本机私有配置，与 Git 处理一致；公共 .env 与 dev/test/prod 随上下文构建。
+**/.env.local
+**/.env.*.local
+**/.env.runtime
+**/.hai/deploy

package/templates/apps/fullstack/.gitignore.hbs

@@ -1,17 +1,30 @@
+# 构建产物目录
 node_modules
-**/data/
-.turbo
-dist
 build
+dist
+.turbo
+android
+ios
 **/src/lib/paraglide
-playwright-report
-test-results
-.env
-.env.*
-!.env.example
-!.env.example.hbs
 **/src-tauri/gen/
 **/src-tauri/target/
+**/hash-core/target/
+
+# 日志测试目录
+*.log
+test-results/
+playwright-report/
+
+
+# 系统文件
+.DS_Store
+
+# 本地数据目录
+**/data/
 
 # hai deploy 产物（compose / .env.runtime / 镜像 tar / sidecar 凭据）
 .hai/
+
+# 本机私有配置；公共 .env 与 dev/test/prod 环境文件纳入版本控制。
+.env.local
+.env.*.local

package/templates/apps/fullstack/Dockerfile.hbs

@@ -1,5 +1,11 @@
 # syntax=docker/dockerfile:1.7
 FROM node:24-bookworm-slim AS build
+ARG SQLITE_PREBUILD_MIRROR
+ENV npm_config_better_sqlite3_binary_host_mirror=$SQLITE_PREBUILD_MIRROR
+ARG HAI_DEPLOY_ENVIRONMENT=prod
+ARG HAI_CORE_ENV=production
+ENV HAI_DEPLOY_ENVIRONMENT=$HAI_DEPLOY_ENVIRONMENT
+ENV HAI_CORE_ENV=$HAI_CORE_ENV
 
 ENV PNPM_HOME=/pnpm
 ENV PATH=$PNPM_HOME:$PATH
@@ -15,12 +21,16 @@ RUN pnpm build
 
 FROM build AS service-build
 
+RUN 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 pnpm pm deploy --filter {{fullstack.servPackageName}} --prod /prod/service
 
 FROM node:24-bookworm-slim AS service
+ARG HAI_DEPLOY_ENVIRONMENT=prod
+ARG HAI_CORE_ENV=production
 
 ENV NODE_ENV=production
-ENV HAI_CORE_ENV=production
+ENV HAI_DEPLOY_ENVIRONMENT=$HAI_DEPLOY_ENVIRONMENT
+ENV HAI_CORE_ENV=$HAI_CORE_ENV
 ENV HOST=0.0.0.0
 ENV PORT=3000
 WORKDIR /app

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

@@ -9,13 +9,18 @@
   "scripts": {
     "paraglide:compile": "paraglide-js compile --project ./project.inlang --outdir ./src/lib/paraglide",
     "paraglide:watch": "paraglide-js compile --project ./project.inlang --outdir ./src/lib/paraglide --watch",
+    "dev:test": "vite --mode test",
+    "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",
     "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "test": "pnpm paraglide:compile && vitest run --passWithNoTests",
     "test:watch": "pnpm paraglide:compile && vitest",
     "clean": "rimraf dist build android ios .turbo src/lib/paraglide",
@@ -50,6 +55,7 @@
     "@capacitor/preferences": "{{fullstack.packageSpecifiers.capacitorPreferences}}",
     "@capacitor/push-notifications": "{{fullstack.packageSpecifiers.capacitorPushNotifications}}",
     "@capacitor/status-bar": "{{fullstack.packageSpecifiers.capacitorStatusBar}}",
+    "@h-ai/core": "{{haiPackageSpecifier}}",
     "@iconify-json/tabler": "{{fullstack.packageSpecifiers.iconifyJsonTabler}}",
     "@iconify/tailwind4": "{{fullstack.packageSpecifiers.iconifyTailwind}}",
     "@inlang/paraglide-js": "{{fullstack.packageSpecifiers.inlangParaglide}}",

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

@@ -2,21 +2,25 @@
 {{#if fullstack.frontends.app}}
 import process from 'node:process'
 import { fileURLToPath } from 'node:url'
+import { core } from '@h-ai/core'
 import { haiOptimizeExclude, haiPrebundledDeps } from '@h-ai/ui/vite'
 import { paraglideVitePlugin } from '@inlang/paraglide-js'
 import { svelte } from '@sveltejs/vite-plugin-svelte'
 import tailwindcss from '@tailwindcss/vite'
-import { loadEnv } from 'vite'
 import { defineConfig } from 'vitest/config'
 
 const envDir = fileURLToPath(new URL('../../', import.meta.url))
 
 export default defineConfig(({ mode }) => {
-  const env = loadEnv(mode, envDir, 'PUBLIC_')
+  const envResult = core.config.loadEnvFiles({ mode, envDir })
+  if (!envResult.success)
+    throw new Error(envResult.error.message)
+  const env = envResult.data
+  Object.assign(process.env, env)
   const target = (env.PUBLIC_API_BASE || process.env.SERVICE_BASE_URL || 'http://127.0.0.1:3000').replace(/\/api\/v1\/?$/, '')
   const proxy = { '/api': { target, changeOrigin: true } }
   return {
-    envDir,
+    envDir: false,
     server: { proxy },
     preview: { proxy },
     build: {

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

@@ -9,11 +9,15 @@
   "scripts": {
     "paraglide:compile": "paraglide-js compile --project ./project.inlang --outdir ./src/lib/paraglide",
     "paraglide:watch": "paraglide-js compile --project ./project.inlang --outdir ./src/lib/paraglide --watch",
+    "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",
     "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",
     "lint": "eslint src vite.config.ts svelte.config.js",
     "lint:fix": "eslint src vite.config.ts svelte.config.js --fix",
@@ -31,6 +35,7 @@
   },
   "devDependencies": {
     "@antfu/eslint-config": "{{fullstack.packageSpecifiers.antfuEslintConfig}}",
+    "@h-ai/core": "{{haiPackageSpecifier}}",
     "@iconify-json/tabler": "{{fullstack.packageSpecifiers.iconifyJsonTabler}}",
     "@iconify/tailwind4": "{{fullstack.packageSpecifiers.iconifyTailwind}}",
     "@inlang/paraglide-js": "{{fullstack.packageSpecifiers.inlangParaglide}}",

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

@@ -2,23 +2,27 @@
 {{#if fullstack.frontends.desktop}}
 import process from 'node:process'
 import { fileURLToPath } from 'node:url'
+import { core } from '@h-ai/core'
 import { haiOptimizeExclude, haiPrebundledDeps } from '@h-ai/ui/vite'
 import { paraglideVitePlugin } from '@inlang/paraglide-js'
 import { svelte } from '@sveltejs/vite-plugin-svelte'
 import tailwindcss from '@tailwindcss/vite'
-import { loadEnv } from 'vite'
 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 env = loadEnv(mode, envDir, 'PUBLIC_')
+  const envResult = core.config.loadEnvFiles({ mode, envDir })
+  if (!envResult.success)
+    throw new Error(envResult.error.message)
+  const env = envResult.data
+  Object.assign(process.env, env)
   const target = (env.PUBLIC_API_BASE || process.env.SERVICE_BASE_URL || 'http://127.0.0.1:3000').replace(/\/api\/v1\/?$/, '')
   const proxy = { '/api': { target, changeOrigin: true } }
 
   return {
-    envDir,
+    envDir: false,
     preview: { proxy },
     build: {
       rolldownOptions: {

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

@@ -9,13 +9,18 @@
   "scripts": {
     "paraglide:compile": "paraglide-js compile --project ./project.inlang --outdir ./src/lib/paraglide",
     "paraglide:watch": "paraglide-js compile --project ./project.inlang --outdir ./src/lib/paraglide --watch",
+    "dev:test": "vite --mode test",
+    "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",
     "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "test": "vitest run --passWithNoTests",
     "test:watch": "vitest",
     "clean": "rimraf dist build .turbo src/lib/paraglide"
@@ -26,6 +31,7 @@
   },
   "devDependencies": {
     "@antfu/eslint-config": "{{fullstack.packageSpecifiers.antfuEslintConfig}}",
+    "@h-ai/core": "{{haiPackageSpecifier}}",
     "@iconify-json/tabler": "{{fullstack.packageSpecifiers.iconifyJsonTabler}}",
     "@iconify/tailwind4": "{{fullstack.packageSpecifiers.iconifyTailwind}}",
     "@inlang/paraglide-js": "{{fullstack.packageSpecifiers.inlangParaglide}}",

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

@@ -2,21 +2,25 @@
 {{#if fullstack.frontends.web}}
 import process from 'node:process'
 import { fileURLToPath } from 'node:url'
+import { core } from '@h-ai/core'
 import { haiOptimizeExclude, haiPrebundledDeps } from '@h-ai/ui/vite'
 import { paraglideVitePlugin } from '@inlang/paraglide-js'
 import { svelte } from '@sveltejs/vite-plugin-svelte'
 import tailwindcss from '@tailwindcss/vite'
-import { loadEnv } from 'vite'
 import { defineConfig } from 'vitest/config'
 
 const envDir = fileURLToPath(new URL('../../', import.meta.url))
 
 export default defineConfig(({ mode }) => {
-  const env = loadEnv(mode, envDir, 'PUBLIC_')
+  const envResult = core.config.loadEnvFiles({ mode, envDir })
+  if (!envResult.success)
+    throw new Error(envResult.error.message)
+  const env = envResult.data
+  Object.assign(process.env, env)
   const target = (env.PUBLIC_API_BASE || process.env.SERVICE_BASE_URL || 'http://127.0.0.1:3000').replace(/\/api\/v1\/?$/, '')
   const proxy = { '/api': { target, changeOrigin: true } }
   return {
-    envDir,
+    envDir: false,
     server: { proxy },
     preview: { proxy },
     build: {

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

@@ -61,6 +61,98 @@ test('service rejects plaintext business requests', async ({ request }) => {
 })
 
 {{#if fullstack.e2eFrontend}}
+test('hash routing restores direct links, refresh and browser history', async ({ page }) => {
+  await page.goto('/#/roles?source=direct')
+  await login(page, 'admin', adminPassword)
+  await expect(page.getByTestId('roles-page')).toBeVisible()
+  await expect(page).toHaveURL(/#\/roles\?source=direct$/)
+  await page.reload()
+  await expect(page.getByTestId('roles-page')).toBeVisible()
+  await expect(page.locator('header')).toBeVisible()
+  await expect(page.locator('footer')).toBeVisible()
+  await page.getByTestId('nav-settings').click()
+  await expect(page).toHaveURL(/#\/settings$/)
+  await page.goBack()
+  await expect(page.getByTestId('roles-page')).toBeVisible()
+  await page.goForward()
+  await expect(page.getByTestId('profile-form')).toBeVisible()
+  await page.goto('/#/unknown-page')
+  await expect(page).toHaveURL(/#\/users$/)
+  await expect(page.getByTestId('users-page')).toBeVisible()
+})
+
+test('branded authentication, profile layout and blur validation work across screen sizes', async ({ page }, testInfo) => {
+  test.setTimeout(60_000)
+  await page.setViewportSize({ width: 1440, height: 960 })
+  await page.goto('/')
+  await expect(page.getByRole('heading', { name: configuredName, exact: true })).toBeVisible()
+  await expect(page.locator('header')).toBeVisible()
+  await expect(page.locator('footer')).toBeVisible()
+  await capture(page, '{{projectName}}-login-desktop.png', testInfo.outputPath('login-desktop.png'))
+  await page.getByRole('button', { name: /立即注册|Register now/, exact: true }).click()
+  await expect(page.locator('.register-form')).toBeVisible()
+  await capture(page, '{{projectName}}-register-desktop.png', testInfo.outputPath('register-desktop.png'))
+  await page.setViewportSize({ width: 390, height: 844 })
+  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 capture(page, '{{projectName}}-login-mobile.png', testInfo.outputPath('login-mobile.png'))
+  await page.setViewportSize({ width: 1440, height: 960 })
+  await login(page, 'admin', adminPassword)
+  await page.getByTestId('nav-settings').click()
+  const profile = page.getByTestId('profile-form')
+  await expect(profile).toBeVisible()
+  const email = profile.locator('input[name="email"]')
+  await email.fill('invalid-email')
+  await email.press('Tab')
+  await expect(email).toHaveAttribute('aria-invalid', 'true')
+  await capture(page, '{{projectName}}-profile-blur-error.png', testInfo.outputPath('profile-blur-error.png'))
+  await email.fill('')
+  await expect(email).not.toHaveAttribute('aria-invalid')
+  await capture(page, '{{projectName}}-settings-desktop.png', testInfo.outputPath('settings-desktop.png'))
+  for (const width of [768, 390]) {
+    await page.setViewportSize({ width, height: 960 })
+    const fields = await profile.locator('.hai-form-field').evaluateAll(elements => elements.map((field) => {
+      const label = field.querySelector('label')!.getBoundingClientRect()
+      const control = field.querySelector('input')!.getBoundingClientRect()
+      return { labelBottom: label.bottom, controlTop: control.top, controlRight: control.right }
+    }))
+    for (const field of fields) {
+      expect(field.labelBottom).toBeLessThanOrEqual(field.controlTop)
+      expect(field.controlRight).toBeLessThanOrEqual(width)
+    }
+    expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
+    await capture(page, `{{projectName}}-settings-${width}.png`, testInfo.outputPath(`settings-${width}.png`))
+  }
+  await page.getByTestId('password-form').scrollIntoViewIfNeeded()
+  await capture(page, '{{projectName}}-password-mobile.png', testInfo.outputPath('password-mobile.png'))
+  await page.setViewportSize({ width: 1440, height: 960 })
+  await page.getByTestId('nav-users').click()
+  await page.getByTestId('create-user').click()
+  const username = page.getByTestId('user-username').locator('input')
+  await username.focus()
+  await username.press('Tab')
+  await expect(username).toHaveAttribute('aria-invalid', 'true')
+  await username.fill('a')
+  await expect(username).toHaveAttribute('aria-invalid', 'true')
+  await page.getByTestId('user-password').locator('input').fill('short')
+  await page.getByTestId('user-password').locator('input').press('Tab')
+  await expect(page.getByTestId('user-password').locator('input')).toHaveAttribute('aria-invalid', 'true')
+  await capture(page, '{{projectName}}-create-blur-error.png', testInfo.outputPath('create-blur-error.png'))
+  await page.getByTestId('user-editor').getByRole('button', { name: /取消|Cancel/, exact: true }).click()
+  await page.getByTestId('create-user').click()
+  await expect(page.getByTestId('user-editor').locator('[aria-invalid="true"]')).toHaveCount(0)
+  await page.getByTestId('user-editor').getByRole('button', { name: /取消|Cancel/, exact: true }).click()
+  await userEditor(page, 'admin')
+  const editEmail = page.getByTestId('user-email').locator('input')
+  await editEmail.fill('invalid-email')
+  await editEmail.press('Tab')
+  await expect(editEmail).toHaveAttribute('aria-invalid', 'true')
+  await capture(page, '{{projectName}}-edit-blur-error.png', testInfo.outputPath('edit-blur-error.png'))
+  await editEmail.fill('admin@example.com')
+  await expect(editEmail).not.toHaveAttribute('aria-invalid')
+})
+
 test('first-use tour, help search and settings navigation work on desktop and mobile', async ({ page }, testInfo) => {
   await page.goto('/')
   await login(page, 'admin', adminPassword, true)
@@ -109,7 +201,7 @@ const additionalFrontends = [
 {{#each fullstack.frontendApps}}
   {
     target: '{{target}}',
-    url: process.env.HAI_E2E_{{target}}_URL || 'http://127.0.0.1:{{port}}',
+    url: process.env['HAI_E2E_{{target}}_URL'.toUpperCase()] || 'http://127.0.0.1:{{port}}',
   },
 {{/each}}
 ].filter(frontend => frontend.target !== '{{fullstack.e2eFrontend.target}}')

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

@@ -10,6 +10,12 @@
     "i18n:compile": "pnpm --filter {{fullstack.sharedPackageName}} paraglide:compile{{#each fullstack.frontendApps}} && pnpm --filter {{packageName}} paraglide:compile{{/each}}",
     "postinstall": "pnpm i18n:compile",
     "dev": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm --parallel --filter {{fullstack.servPackageName}}{{#each fullstack.frontendApps}} --filter {{packageName}}{{/each}} dev",
+    "start": "pnpm --filter {{fullstack.servPackageName}} start",
+    "start:test": "pnpm --filter {{fullstack.servPackageName}} start:test",
+    "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 .",
@@ -20,9 +26,12 @@
     "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",
+    "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",
     "clean": "pnpm -r --if-present clean && rimraf node_modules .turbo"
   },
@@ -32,6 +41,9 @@
     "{{fullstack.sharedPackageName}}": "workspace:*"
   },
   "devDependencies": {
+{{#if features.deploy}}
+    "@h-ai/deploy": "{{haiPackageSpecifier}}",
+{{/if}}
     "@antfu/eslint-config": "{{fullstack.packageSpecifiers.antfuEslintConfig}}",
     "@playwright/test": "{{fullstack.packageSpecifiers.playwright}}",
     "@sveltejs/vite-plugin-svelte": "{{fullstack.packageSpecifiers.sveltePlugin}}",

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

@@ -1,12 +1,12 @@
 # {{fullstack.contractPackageName}}
 
-共享 API 契约包，包含 Zod Schema、`apiContract.route()` 业务接口定义与工程级 contract。
+共享 API 契约包，包含 Zod Schema、`apiContract.route()` 业务接口定义与工程级 contract。业务 schema、角色、流程及限额是模板初始方案，按用户需求修改，并同步服务端授权、调用方、测试与说明；不要求需求沿用默认业务。
 
 ## 骨架说明
 
 - `src/app-schemas.ts`：跨接口、跨层复用的输入/数据 Schema 与类型。
 - `src/app-contract.ts`：app 领域 contract；每个业务 path 直接写在对应接口定义中。
-- `src/admin-schemas.ts` / `src/admin-contract.ts`：管理员用户、固定角色、分页审计、个人设置、加密 JSON 头像上传 Schema/类型/路由；认证复用框架的 IAM auth contract，通过服务端配置启用注册、密码/LDAP/验证码登录及密码重置。
+- `src/admin-schemas.ts` / `src/admin-contract.ts`：示例管理员用户、初始 admin/user 角色、分页审计、个人设置、加密 JSON 头像上传 Schema/类型/路由；认证复用框架的 IAM auth contract，通过服务端配置启用注册、密码/LDAP/验证码登录及密码重置。
 - `src/{{projectName}}-contract.ts`：工程级 contract，供 `@h-ai/serv` 与 `@h-ai/api-client` 共用。
 
 只使用一次的输出 Schema 直接内联到 `.output(...)`；同一 contract 文件内重复使用时才保留私有常量。

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

@@ -14,8 +14,10 @@
   "types": "./dist/index.d.ts",
   "scripts": {
     "build": "tsup",
+    "check": "pnpm typecheck",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "test": "vitest run",
     "test:watch": "vitest",
     "clean": "rimraf dist .turbo"