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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "0.1.0-alpha.64",
+  "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.64",
+    "@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.64",
-    "@h-ai/deploy": "0.1.0-alpha.64",
-    "@h-ai/reach": "0.1.0-alpha.64",
-    "@h-ai/reldb": "0.1.0-alpha.64",
-    "@h-ai/storage": "0.1.0-alpha.64",
+    "@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,11 +61,33 @@ 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()
@@ -179,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"

package/templates/apps/fullstack/packages/{{projectName}}-contract/src/admin-contract.ts.hbs

@@ -14,7 +14,7 @@ import {
   ProfileUpdateSchema,
 } from './admin-schemas.js'
 
-/** mini 管理业务路径统一定义；仅开放两种固定角色。 */
+/** mini 管理示例的业务路径；初始 admin/user 角色可按实际需求调整。 */
 export const adminContract = {
   users: {
     list: apiContract.route({ method: 'POST', path: '/admin/users/list', tags: ['admin'] })

package/templates/apps/fullstack/packages/{{projectName}}-contract/tests/contract.test.ts.hbs

@@ -1,36 +1,30 @@
 import { apiContract } from '@h-ai/api-contract'
 import { describe, expect, it } from 'vitest'
-import {
-  appContract,
-  AppEchoInputSchema,
-  AppInfoOutputDataSchema,
-  ENABLED_FRONTENDS,
-  {{fullstack.contractExportName}},
-} from '../src/index.js'
+import * as contracts from '../src/index.js'
 
 describe('{{fullstack.contractPackageName}}', () => {
   it('defines app contract routes', () => {
-    expect({{fullstack.contractExportName}}.app).toBeDefined()
-    expect(appContract.info).toBeDefined()
-    expect(apiContract.pathOf(appContract.info)).toBe('/app/info')
+    expect(contracts.{{fullstack.contractExportName}}.app).toBeDefined()
+    expect(contracts.appContract.info).toBeDefined()
+    expect(apiContract.pathOf(contracts.appContract.info)).toBe('/app/info')
   })
 
   it('validates app info payload', () => {
-    const result = AppInfoOutputDataSchema.safeParse({
+    const result = contracts.AppInfoOutputDataSchema.safeParse({
       name: '{{fullstack.servPackageName}}',
       version: '0.1.0',
       env: 'test',
       defaultLocale: 'zh-CN',
       supportedLocales: ['zh-CN', 'en-US'],
       startedAt: '2026-01-01T00:00:00.000Z',
-      frontends: [...ENABLED_FRONTENDS],
+      frontends: [...contracts.ENABLED_FRONTENDS],
     })
 
     expect(result.success).toBe(true)
   })
 
   it('validates echo input boundaries', () => {
-    expect(AppEchoInputSchema.safeParse({ message: 'hello' }).success).toBe(true)
-    expect(AppEchoInputSchema.safeParse({ message: '' }).success).toBe(false)
+    expect(contracts.AppEchoInputSchema.safeParse({ message: 'hello' }).success).toBe(true)
+    expect(contracts.AppEchoInputSchema.safeParse({ message: '' }).success).toBe(false)
   })
 })