@h-ai/cli 0.1.0-alpha.15 → 0.1.0-alpha.18

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "0.1.0-alpha.15",
+  "version": "0.1.0-alpha.18",
   "description": "Hai Framework CLI for project scaffolding and code generation.",
   "license": "Apache-2.0",
   "keywords": [
@@ -34,16 +34,16 @@
     "ora": "^9.1.0",
     "prompts": "^2.4.2",
     "yaml": "^2.7.0",
-    "@h-ai/core": "0.1.0-alpha.15"
+    "@h-ai/core": "0.1.0-alpha.18"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
-    "@types/node": "^25.1.0",
+    "@types/node": "^25.9.1",
     "@types/prompts": "^2.4.9",
-    "rimraf": "^6.0.1",
-    "tsup": "^8.3.5",
-    "typescript": "^6.0.2",
-    "vitest": "^4.0.18"
+    "rimraf": "^6.1.3",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
   },
   "scripts": {
     "build": "tsup",
@@ -52,6 +52,7 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "test": "vitest run",
+    "test:scaffold-gates": "pnpm build && node tests/run-scaffold-gates.mjs",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "clean": "rimraf dist .turbo"

package/templates/README.md

@@ -31,8 +31,12 @@ templates/
 │   ├── h5/                  # H5 移动端
 │   │   ├── messages/
 │   │   └── src/routes/
-│   └── api/                 # 纯 API 服务（无 UI / 无 i18n）
-│       └── src/routes/
+│   ├── api/                 # 纯 API 服务（无 UI / 无 i18n）
+│   │   └── src/routes/
+│   └── fullstack/           # 前后端分离多包工程（contract / serv / web / app / desktop / miniapp 占位）
+│       ├── packages/        # 共享 contract 与后端 serv 包
+│       ├── apps/            # 多前端目标，按用户选择条件生成
+│       └── e2e/             # 服务端 + 页面级 Playwright 流程
 │
 ├── features/                # 可选 feature 路由（叠加到 src/routes/）
 │   ├── iam/
@@ -81,6 +85,7 @@ templates/
 | `{{hasI18n}}`          | `boolean` | 是否启用 i18n（非 `api` 类型为 `true`）      |
 | `{{defaultLocale}}`    | `string`  | 默认语言，如 `zh-CN`                         |
 | `{{packageManager}}`   | `string`  | 包管理器：`pnpm` / `npm` / `yarn`            |
+| `{{fullstack.*}}`      | `object`  | fullstack 类型专用上下文                     |
 | `{{features.iam}}`     | `boolean` | 是否选中 iam feature                         |
 | `{{features.db}}`      | `boolean` | 是否选中 db feature                          |
 | `{{features.cache}}`   | `boolean` | 是否选中 cache feature                       |
@@ -88,6 +93,8 @@ templates/
 | `{{features.storage}}` | `boolean` | 是否选中 storage feature                     |
 | `{{features.ai}}`      | `boolean` | 是否选中 ai feature                          |
 
+`fullstack.*` 包含包名、前端选择、依赖版本和 `contractExportName`，用于渲染 contract / serv / 多端 UI 的模板。
+
 ### 常用条件写法
 
 ```handlebars
@@ -123,4 +130,4 @@ import { iam } from '@h-ai/iam'
 
 ### 新增 feature 路由
 
-在 `features/{featureId}/routes-shared/`（API 路由）或 `features/{featureId}/routes-{appType}/`（UI 页面）下创建文件，然后在 `template-engine.ts` 的 `FEATURE_ROUTE_DIRS` / `FEATURE_APP_ROUTE_DIRS` 中注册该目录。
+在 `features/{featureId}/routes-shared/`（API 路由）或 `features/{featureId}/routes-{appType}/`（UI 页面）下创建文件，然后在 `cli-template-engine.ts` 的 `FEATURE_ROUTE_DIRS` / `FEATURE_APP_ROUTE_DIRS` 中注册该目录。

package/templates/apps/api/tests/health.test.ts.hbs

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest'
+import { GET } from '../src/routes/api/v1/health/+server'
+
+interface HealthResponseBody {
+  success: boolean
+  data?: {
+    status?: string
+    service?: string
+  }
+  requestId?: string
+}
+
+describe('api health endpoint', () => {
+  it('returns a successful HaiResult response', async () => {
+    const response = await GET({
+      locals: { requestId: 'test-request' },
+    } as Parameters<typeof GET>[0])
+    const body = await response.json() as HealthResponseBody
+
+    expect(response.status).toBe(200)
+    expect(body.success).toBe(true)
+    expect(body.data?.status).toBe('ok')
+    expect(body.data?.service).toBe('api-service')
+    expect(body.requestId).toBe('test-request')
+  })
+})

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

@@ -0,0 +1,21 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.app}}
+# {{projectName}}-app
+
+App/H5 前端工程，使用 `@h-ai/api-client` 绑定共享 contract 调用后端 API，并通过 `@h-ai/ui` 组件搭建页面。
+
+## i18n 与 shared 协同
+
+- 本端页面文案：`messages/{locale}.json` + `project.inlang/settings.json`
+- 共享 Shell/主题/语言/API：`packages/{{fullstack.sharedPackageName}}`
+- 语言切换由 shared 的 `LanguageSwitcher` 触发，并同步本端 `$lib/paraglide/runtime.js`
+
+自定义建议：移动端独有引导、运营位、按钮文案放在本目录 `messages/`；跨端通用组件放到 shared。
+
+## 开发
+
+- `pnpm i18n:compile`：在工作区根目录统一编译 shared + 各前端 Paraglide 输出
+- `pnpm --filter {{projectName}}-app dev`，默认端口 4174
+- `pnpm --filter {{projectName}}-app paraglide:compile`：只编译本端 messages
+- `pnpm --filter {{projectName}}-app test`
+{{/if}}

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

@@ -0,0 +1,23 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.app}}
+import antfu from '@antfu/eslint-config'
+
+export default antfu({
+  formatters: true,
+  ignores: ['**/.svelte-kit/**', '**/build/**', '**/dist/**', '**/*.d.ts', '**/project.inlang/**', '**/src/lib/paraglide/**'],
+  svelte: true,
+}, {
+  files: ['**/*.ts', '**/*.svelte'],
+  rules: {
+    'no-console': 'error',
+    'ts/no-explicit-any': 'error',
+  },
+}, {
+  files: ['**/*.svelte'],
+  rules: {
+    'svelte/html-quotes': 'off',
+    'svelte/indent': 'off',
+    'perfectionist/sort-imports': 'off',
+  },
+})
+{{/if}}

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

@@ -0,0 +1,34 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.app}}
+{
+  "$schema": "https://inlang.com/schema/inlang-message-format",
+  "page_title": "{name} · App",
+  "platform_name": "App/H5",
+  "hero_badge": "Mobile workspace",
+  "hero_title": "{name} App Experience",
+  "hero_subtitle": "A mobile and H5 oriented entry point. This app keeps its own messages so onboarding and campaign copy can evolve independently.",
+  "hero_primary_action": "View service status",
+  "hero_secondary_action": "Customize the starter",
+  "preview_title": "Mobile-first interface",
+  "preview_body": "Ready for H5, Capacitor or embedded WebViews",
+  "preview_metric_shared": "Shared shell and API",
+  "preview_metric_local": "App-owned messages",
+  "preview_metric_theme": "Theme from config",
+  "status_title": "Service connectivity",
+  "status_description": "The mobile page calls the same backend API to verify cross-platform contract and shared API client wiring.",
+  "status_online": "{name} is connected",
+  "status_version": "Service version",
+  "status_started": "Started at: {time}",
+  "status_frontends": "Service frontends: {list}",
+  "status_frontends_count": "{count} frontend targets",
+  "custom_shared_title": "Shared owns common capabilities",
+  "custom_shared_body": "Keep cross-platform layout, locale, theme and API access in packages/{{projectName}}-shared.",
+  "custom_local_title": "App owns mobile copy",
+  "custom_local_body": "Write App-specific copy in apps/{{projectName}}-app/messages so mobile UX can iterate independently.",
+  "flow_title": "Collaboration boundary",
+  "flow_contract": "Contract constrains requests/responses",
+  "flow_service": "Service exposes unified APIs",
+  "flow_shared": "Shared reuses cross-platform capabilities",
+  "flow_frontend": "App composes the mobile experience"
+}
+{{/if}}

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

@@ -0,0 +1,34 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.app}}
+{
+  "$schema": "https://inlang.com/schema/inlang-message-format",
+  "page_title": "{name} · App",
+  "platform_name": "App/H5",
+  "hero_badge": "移动端工作台",
+  "hero_title": "{name} App 体验",
+  "hero_subtitle": "面向移动端与 H5 场景的轻量入口，保留本端 messages 以便独立调整文案、引导语和运营内容。",
+  "hero_primary_action": "查看服务状态",
+  "hero_secondary_action": "了解如何自定义",
+  "preview_title": "移动优先界面",
+  "preview_body": "适合 H5、Capacitor 或内嵌 WebView",
+  "preview_metric_shared": "共享 Shell 与接口",
+  "preview_metric_local": "App 自有 messages",
+  "preview_metric_theme": "主题跟随配置",
+  "status_title": "服务联通状态",
+  "status_description": "移动端页面会调用同一套后端 API，验证跨端 contract 与 shared API client 正常工作。",
+  "status_online": "{name} 已连接",
+  "status_version": "服务版本",
+  "status_started": "启动时间：{time}",
+  "status_frontends": "服务声明的前端：{list}",
+  "status_frontends_count": "{count} 个前端目标",
+  "custom_shared_title": "共享层放通用能力",
+  "custom_shared_body": "跨端一致的布局、语言、主题和 API 访问都放在 packages/{{projectName}}-shared。",
+  "custom_local_title": "App 层放移动文案",
+  "custom_local_body": "App 独有文案写在 apps/{{projectName}}-app/messages，便于移动端独立迭代。",
+  "flow_title": "协同边界",
+  "flow_contract": "Contract 约束请求响应",
+  "flow_service": "Service 提供统一 API",
+  "flow_shared": "Shared 复用跨端能力",
+  "flow_frontend": "App 组织移动端体验"
+}
+{{/if}}

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

@@ -0,0 +1,50 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.app}}
+{
+  "name": "{{projectName}}-app",
+  "type": "module",
+  "version": "0.1.0",
+  "private": true,
+  "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": "vite dev --host 127.0.0.1 --port {{fullstack.ports.app}}",
+    "build": "vite build",
+    "preview": "vite preview --host 127.0.0.1 --port {{fullstack.ports.app}} --strictPort",
+    "typecheck": "pnpm paraglide:compile && svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rimraf .svelte-kit build .turbo src/lib/paraglide"
+  },
+  "dependencies": {
+    "@h-ai/api-client": "{{fullstack.versions.apiClient}}",
+    "@h-ai/ui": "{{fullstack.versions.ui}}",
+    "{{fullstack.contractPackageName}}": "workspace:*",
+    "{{fullstack.sharedPackageName}}": "workspace:*"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "{{fullstack.versions.antfuEslintConfig}}",
+    "@iconify-json/tabler": "{{fullstack.versions.iconifyJsonTabler}}",
+    "@iconify/tailwind4": "{{fullstack.versions.iconifyTailwind}}",
+    "@inlang/paraglide-js": "{{fullstack.versions.inlangParaglide}}",
+    "@inlang/plugin-message-format": "{{fullstack.versions.inlangMessageFormat}}",
+    "@sveltejs/adapter-auto": "{{fullstack.versions.adapterAuto}}",
+    "@sveltejs/kit": "{{fullstack.versions.svelteKit}}",
+    "@sveltejs/vite-plugin-svelte": "{{fullstack.versions.sveltePlugin}}",
+    "@tailwindcss/vite": "{{fullstack.versions.tailwindcssVite}}",
+    "bits-ui": "{{fullstack.versions.bitsUi}}",
+    "daisyui": "{{fullstack.versions.daisyui}}",
+    "eslint": "{{fullstack.versions.eslint}}",
+    "eslint-plugin-format": "{{fullstack.versions.eslintPluginFormat}}",
+    "eslint-plugin-svelte": "{{fullstack.versions.eslintPluginSvelte}}",
+    "svelte": "{{fullstack.versions.svelte}}",
+    "svelte-check": "{{fullstack.versions.svelteCheck}}",
+    "svelte-eslint-parser": "{{fullstack.versions.svelteEslintParser}}",
+    "tailwindcss": "{{fullstack.versions.tailwindcss}}",
+    "typescript": "{{fullstack.versions.typescript}}",
+    "vite": "{{fullstack.versions.vite}}",
+    "vitest": "{{fullstack.versions.vitest}}"
+  }
+}
+{{/if}}

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

@@ -0,0 +1,17 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.app}}
+{
+  "$schema": "https://inlang.com/schema/project-settings",
+  "baseLocale": "{{fullstack.i18n.baseLocale}}",
+  "locales": [
+    {{#each fullstack.i18n.locales}}"{{this}}"{{#unless @last}},{{/unless}}
+    {{/each}}
+  ],
+  "modules": [
+    "https://cdn.jsdelivr.net/npm/@inlang/plugin-message-format@latest/dist/index.js"
+  ],
+  "plugin.inlang.messageFormat": {
+    "pathPattern": "./messages/{locale}.json"
+  }
+}
+{{/if}}

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

@@ -0,0 +1,18 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.app}}
+@import 'tailwindcss';
+@import '@h-ai/ui/styles/global.css';
+@import '@h-ai/ui/styles/theme.css';
+@source "../node_modules/@h-ai/ui/dist/**/*.{svelte,js,ts}";
+@source "../../../node_modules/@h-ai/ui/dist/**/*.{svelte,js,ts}";
+@source "../../../packages/{{fullstack.sharedPackageName}}/src/**/*.{svelte,js,ts}";
+
+@plugin "daisyui" {
+  themes:
+    {{#each fullstack.theme.themes}}{{this}}{{#if_eq this ../fullstack.theme.defaultTheme}} --default{{/if_eq}}{{#unless @last}},
+    {{/unless}}{{/each}};
+}
+@plugin "@iconify/tailwind4" {
+  prefixes: tabler;
+}
+{{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-app/src/app.d.ts.hbs

@@ -0,0 +1,9 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.app}}
+/// <reference types="@sveltejs/kit" />
+/// <reference types="vite/client" />
+
+import '@h-ai/ui/auto-import'
+
+declare module '*.css'
+{{/if}}

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

@@ -0,0 +1,14 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.app}}
+<!doctype html>
+<html lang="%paraglide.lang%">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    %sveltekit.head%
+  </head>
+  <body data-sveltekit-preload-data="hover">
+    <div style="display: contents">%sveltekit.body%</div>
+  </body>
+</html>
+{{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-app/src/routes/+layout.svelte.hbs

@@ -0,0 +1,18 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.app}}
+<script lang="ts">
+  import { setLocale } from '$lib/paraglide/runtime.js'
+  import { AppShell } from '{{fullstack.sharedPackageName}}'
+  import '../app.css'
+
+  const { children } = $props()
+
+  function syncLocale(locale: string) {
+    setLocale(locale as Parameters<typeof setLocale>[0])
+  }
+</script>
+
+<AppShell platform="app" onLocaleChange={syncLocale}>
+  {@render children()}
+</AppShell>
+{{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-app/src/routes/+page.svelte.hbs

@@ -0,0 +1,162 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.app}}
+<script lang="ts">
+  import type { AppInfo } from '{{fullstack.sharedPackageName}}'
+  import * as appM from '$lib/paraglide/messages.js'
+  import { Alert, Button, Card, Skeleton } from '@h-ai/ui'
+  import { onMount } from 'svelte'
+  import { fetchAppInfo, messages as sharedM } from '{{fullstack.sharedPackageName}}'
+
+  let info = $state<AppInfo | null>(null)
+  let loading = $state(true)
+  let errorMessage = $state('')
+
+  async function refreshStatus() {
+    loading = true
+    errorMessage = ''
+    try {
+      info = await fetchAppInfo()
+    }
+    catch {
+      info = null
+      errorMessage = sharedM.home_error()
+    }
+    finally {
+      loading = false
+    }
+  }
+
+  onMount(() => {
+    void refreshStatus()
+  })
+</script>
+
+<svelte:head>
+  <title>{appM.page_title({ name: sharedM.app_name() })}</title>
+</svelte:head>
+
+<section class="space-y-8">
+  <div class="grid gap-6 lg:grid-cols-[1.2fr_0.8fr]">
+    <section class="relative overflow-hidden rounded-[2rem] border border-base-300/70 bg-gradient-to-br from-primary/15 via-base-100 to-secondary/15 p-6 shadow-2xl shadow-primary/10 lg:p-10">
+      <div class="absolute right-8 top-8 hidden size-28 rounded-full bg-primary/20 blur-3xl sm:block"></div>
+      <div class="relative z-10 max-w-2xl space-y-6">
+        <span class="badge badge-primary badge-lg gap-2">
+          <span class="icon-[tabler--rocket] size-4"></span>
+          {appM.hero_badge()}
+        </span>
+        <div class="space-y-4">
+          <h1 class="text-4xl font-black tracking-tight text-base-content sm:text-5xl">
+            {appM.hero_title({ name: sharedM.app_name() })}
+          </h1>
+          <p class="max-w-xl text-lg leading-8 text-base-content/70">
+            {appM.hero_subtitle()}
+          </p>
+        </div>
+        <div class="flex flex-wrap gap-3">
+          <a class="btn btn-primary shadow-lg shadow-primary/20" href="#status">
+            <span class="icon-[tabler--activity-heartbeat] size-5"></span>
+            {appM.hero_primary_action()}
+          </a>
+          <a class="btn btn-ghost" href="#customize">
+            <span class="icon-[tabler--adjustments] size-5"></span>
+            {appM.hero_secondary_action()}
+          </a>
+        </div>
+      </div>
+    </section>
+
+    <aside class="rounded-[2rem] border border-base-300/70 bg-base-100/80 p-5 shadow-xl backdrop-blur">
+      <div class="mockup-window border border-base-300 bg-base-200/70">
+        <div class="space-y-4 bg-base-100 p-5">
+          <div class="flex items-center justify-between">
+            <div>
+              <p class="text-sm font-semibold">{appM.preview_title()}</p>
+              <p class="text-xs text-base-content/55">{appM.preview_body()}</p>
+            </div>
+            <span class="badge badge-success badge-outline">{appM.platform_name()}</span>
+          </div>
+          <div class="grid gap-3 text-sm">
+            <div class="rounded-2xl bg-primary/10 p-4">
+              <span class="icon-[tabler--components] mb-2 size-6 text-primary"></span>
+              <p class="font-semibold">{appM.preview_metric_shared()}</p>
+            </div>
+            <div class="grid grid-cols-2 gap-3">
+              <div class="rounded-2xl bg-secondary/10 p-4">
+                <span class="icon-[tabler--language] mb-2 size-6 text-secondary"></span>
+                <p class="font-semibold">{appM.preview_metric_local()}</p>
+              </div>
+              <div class="rounded-2xl bg-accent/10 p-4">
+                <span class="icon-[tabler--palette] mb-2 size-6 text-accent"></span>
+                <p class="font-semibold">{appM.preview_metric_theme()}</p>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </aside>
+  </div>
+
+  <div class="grid gap-6 lg:grid-cols-[0.95fr_1.05fr]">
+    <div id="status">
+    <Card title={appM.status_title()} bordered shadow="md" class="bg-base-100/90 backdrop-blur">
+      <p class="mb-5 text-sm text-base-content/65">{appM.status_description()}</p>
+      {#if loading}
+        <Skeleton variant="title" class="mb-3" />
+        <Skeleton count={3} />
+        <p class="sr-only" data-testid="service-status">{sharedM.home_loading()}</p>
+      {:else if info}
+        <Alert variant="success" title={appM.status_online({ name: info.name })}>
+          <p data-testid="service-status">{info.name}</p>
+        </Alert>
+        <dl class="mt-5 grid gap-3 sm:grid-cols-2 text-sm">
+          <div class="rounded-box border border-base-300/70 bg-base-200/60 p-4">
+            <dt class="text-xs text-base-content/55">{appM.status_version()}</dt>
+            <dd class="mt-1 font-semibold">{info.version}</dd>
+          </div>
+          <div class="rounded-box border border-base-300/70 bg-base-200/60 p-4">
+            <dt class="text-xs text-base-content/55">{appM.status_started({ time: info.startedAt })}</dt>
+            <dd class="mt-1 font-semibold">{appM.status_frontends_count({ count: String(info.frontends.length) })}</dd>
+          </div>
+          <div class="rounded-box border border-base-300/70 bg-base-200/60 p-4 sm:col-span-2">
+            <dt class="text-xs text-base-content/55">{appM.status_frontends({ list: info.frontends.join(' / ') })}</dt>
+            <dd class="mt-1 font-semibold">{sharedM.home_subtitle()}</dd>
+          </div>
+        </dl>
+      {:else}
+        <Alert variant="error" title={sharedM.home_error()}>
+          <p data-testid="service-status">{errorMessage}</p>
+        </Alert>
+      {/if}
+
+      <div class="mt-5">
+        <Button type="button" variant="primary" loading={loading} onclick={refreshStatus}>
+          {sharedM.home_refresh()}
+        </Button>
+      </div>
+    </Card>
+    </div>
+
+    <section id="customize" class="grid gap-4 sm:grid-cols-2">
+      <div class="rounded-[1.5rem] border border-base-300/70 bg-base-100/90 p-5 shadow-md">
+        <span class="icon-[tabler--package] mb-4 size-7 text-primary"></span>
+        <h2 class="text-lg font-bold">{appM.custom_shared_title()}</h2>
+        <p class="mt-2 text-sm leading-6 text-base-content/65">{appM.custom_shared_body()}</p>
+      </div>
+      <div class="rounded-[1.5rem] border border-base-300/70 bg-base-100/90 p-5 shadow-md">
+        <span class="icon-[tabler--message-language] mb-4 size-7 text-secondary"></span>
+        <h2 class="text-lg font-bold">{appM.custom_local_title()}</h2>
+        <p class="mt-2 text-sm leading-6 text-base-content/65">{appM.custom_local_body()}</p>
+      </div>
+      <div class="rounded-[1.5rem] border border-base-300/70 bg-base-100/90 p-5 shadow-md sm:col-span-2">
+        <h2 class="text-lg font-bold">{appM.flow_title()}</h2>
+        <ol class="mt-4 grid gap-3 md:grid-cols-4">
+          <li class="rounded-box bg-base-200/70 p-4 text-sm">{appM.flow_contract()}</li>
+          <li class="rounded-box bg-base-200/70 p-4 text-sm">{appM.flow_service()}</li>
+          <li class="rounded-box bg-base-200/70 p-4 text-sm">{appM.flow_shared()}</li>
+          <li class="rounded-box bg-base-200/70 p-4 text-sm">{appM.flow_frontend()}</li>
+        </ol>
+      </div>
+    </section>
+  </div>
+</section>
+{{/if}}

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

@@ -0,0 +1,20 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.app}}
+import { autoImportHaiUi } from '@h-ai/ui/auto-import'
+import adapter from '@sveltejs/adapter-auto'
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+  preprocess: [autoImportHaiUi(), vitePreprocess()],
+  compilerOptions: {
+    // 使用 Svelte 5 Runes，和 @h-ai/ui 组件库保持一致。
+    runes: true,
+  },
+  kit: {
+    adapter: adapter(),
+  },
+}
+
+export default config
+{{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-app/tests/api.test.ts.hbs

@@ -0,0 +1,28 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.app}}
+import { fetchAppInfo } from '{{fullstack.sharedPackageName}}'
+import { describe, expect, it } from 'vitest'
+
+describe('fetchAppInfo', () => {
+  it('parses shared contract response', async () => {
+    const fetchFn: typeof fetch = async () => new Response(
+      JSON.stringify({
+        success: true,
+        data: {
+          name: '{{fullstack.servPackageName}}',
+          version: '0.1.0',
+          startedAt: '2026-01-01T00:00:00.000Z',
+          frontends: ['app'],
+        },
+      }),
+      {
+        headers: { 'content-type': 'application/json' },
+      },
+    )
+
+    const info = await fetchAppInfo({ fetchFn, baseUrl: 'http://127.0.0.1:3000' })
+
+    expect(info.name).toBe('{{fullstack.servPackageName}}')
+  })
+})
+{{/if}}

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

@@ -0,0 +1,17 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.app}}
+{
+  "extends": "./.svelte-kit/tsconfig.json",
+  "compilerOptions": {
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "allowJs": true,
+    "checkJs": false,
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*", "src/**/*.svelte", "tests/**/*"],
+  "exclude": ["node_modules", ".svelte-kit", "build"]
+}
+{{/if}}

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

@@ -0,0 +1,29 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.app}}
+import { paraglideVitePlugin } from '@inlang/paraglide-js'
+import { sveltekit } from '@sveltejs/kit/vite'
+import tailwindcss from '@tailwindcss/vite'
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  plugins: [
+    paraglideVitePlugin({
+      project: './project.inlang',
+      outdir: './src/lib/paraglide',
+      strategy: ['cookie', 'baseLocale'],
+    }),
+    sveltekit(),
+    tailwindcss(),
+  ],
+  optimizeDeps: {
+    exclude: ['bits-ui'],
+  },
+  ssr: {
+    noExternal: [/@h-ai\//, /{{fullstack.sharedPackageName}}/],
+  },
+  test: {
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+  },
+})
+{{/if}}

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

@@ -0,0 +1,21 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.desktop}}
+# {{projectName}}-desktop
+
+桌面端前端工程，使用 `@h-ai/api-client` 绑定共享 contract 调用后端 API，并通过 `@h-ai/ui` 组件搭建页面；后续可按需接入 Tauri。
+
+## i18n 与 shared 协同
+
+- 本端页面文案：`messages/{locale}.json` + `project.inlang/settings.json`
+- 共享 Shell/主题/语言/API：`packages/{{fullstack.sharedPackageName}}`
+- 语言切换由 shared 的 `LanguageSwitcher` 触发，并同步本端 `$lib/paraglide/runtime.js`
+
+自定义建议：桌面端菜单、状态、快捷操作文案放在本目录 `messages/`；跨端通用能力放到 shared。
+
+## 开发
+
+- `pnpm i18n:compile`：在工作区根目录统一编译 shared + 各前端 Paraglide 输出
+- `pnpm --filter {{projectName}}-desktop dev`，默认端口 4175
+- `pnpm --filter {{projectName}}-desktop paraglide:compile`：只编译本端 messages
+- `pnpm --filter {{projectName}}-desktop test`
+{{/if}}