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

package/templates/apps/mobile-app/src/lib/api.ts.hbs

@@ -1,24 +1,87 @@
 /**
  * {{projectName}} — API 客户端初始化。
  * Web 预览仅使用内存 TokenStore；原生端使用 Capacitor 安全存储。
+ * 原生存储失败会拒绝 Promise；登录/退出调用方须处理 auth.setTokens/clear 失败并释放界面 loading。
  */
 import { apiClient } from '@h-ai/api-client'
 import { createCapacitorTokenStorage } from '@h-ai/capacitor'
+{{#if features.crypto}}
+import { crypto } from '@h-ai/crypto'
+{{/if}}
 
 const DEFAULT_API_BASE = 'http://localhost:3000/api/v1'
 
 let initialized = false
+let initializing: Promise<void> | undefined
+let closing: Promise<void> | undefined
+{{#if features.crypto}}
+// 只关闭本客户端实际初始化的 crypto，保留外部调用方已有实例。
+let ownsCrypto = false
 
+/**
+ * 解析客户端传输选项；仅显式 off 连接匹配的明文 API，握手失败不降级。
+ * @returns 绑定实际 crypto 与公开协商子路径的选项，或显式明文模式的 undefined。
+ * @example 模块内部上下文
+ * ```ts
+ * const transport = resolveTransport()
+ * if (transport) {
+ *   await initApi()
+ *   try {
+ *     if (!apiClient.config?.transport) throw new Error('Transport configuration missing')
+ *   }
+ *   finally { await closeApi() }
+ * }
+ * ```
+ */
+function resolveTransport() {
+  const runtime = (globalThis as typeof globalThis & { __HAI_PUBLIC_CONFIG__?: { apiTransport?: string, apiKeyExchangePath?: string } }).__HAI_PUBLIC_CONFIG__
+  if ((runtime?.apiTransport || import.meta.env.PUBLIC_API_TRANSPORT) === 'off')
+    return undefined
+  return { crypto, keyExchangePath: runtime?.apiKeyExchangePath || import.meta.env.PUBLIC_API_KEY_EXCHANGE_PATH || '/_hai/key-exchange' }
+}
+{{/if}}
+
+/**
+ * 按公开运行配置、构建配置、本地示例地址的顺序解析含 API 前缀的 baseUrl。
+ * @returns API baseUrl；服务端私钥和连接配置不属于该公开地址。
+ * @example 模块内部上下文
+ * ```ts
+ * const base = new URL(resolveApiBase())
+ * const apiOrigin = base.origin
+ * ```
+ */
 export function resolveApiBase(): string {
   const runtime = (globalThis as typeof globalThis & { __HAI_PUBLIC_CONFIG__?: { apiBase?: string } }).__HAI_PUBLIC_CONFIG__
   return runtime?.apiBase || import.meta.env.PUBLIC_API_BASE || DEFAULT_API_BASE
 }
 
+/**
+ * 查询实际 Capacitor 平台，决定安全原生存储或 Web 内存存储。
+ * @returns 是否处于 Capacitor 原生平台；浏览器预览返回 false。
+ * @throws Error - 平台模块加载或检测失败时拒绝 Promise，不伪装为 Web 模式。
+ * @example 模块内部上下文
+ * ```ts
+ * if (await usesNativeTokenStorage()) {
+ *   const storage = createCapacitorTokenStorage()
+ *   const accessToken = await storage.getAccessToken() // 只用于认证，不输出令牌。
+ * }
+ * ```
+ */
 export async function usesNativeTokenStorage(): Promise<boolean> {
   const { Capacitor } = await import('@capacitor/core')
   return Capacitor.isNativePlatform()
 }
 
+/**
+ * 按真实平台创建 TokenStorage；绑定 client 后通过 client.auth 变更身份。
+ * @returns 原生安全存储或 Web 内存存储；其方法的读写故障继续拒绝 Promise。
+ * @throws Error - 平台检测或存储工厂失败时拒绝，不改用较弱的持久化方式。
+ * @example 模块内部上下文
+ * ```ts
+ * const storage = await createTokenStorage()
+ * const accessToken = await storage.getAccessToken() // null 表示未认证，不记录令牌。
+ * ```
+ */
 async function createTokenStorage() {
   if (await usesNativeTokenStorage())
     return createCapacitorTokenStorage()
@@ -26,29 +89,125 @@ async function createTokenStorage() {
   return apiClient.tokenStorage.memory()
 }
 
+/**
+ * 合并在途初始化并等待关闭；安全存储、所选 crypto 与 typed client 依次就绪。
+ * @returns 客户端已准备；重复调用复用同一客户端。
+ * @throws Error - 安全存储、crypto 或 client 初始化失败，业务 HaiResult 在此边界明确转成拒绝。
+ * @throws AggregateError - 初始化和本次 crypto 清理同时失败，后续 closeApi 可重试。
+ * @example 模块内部上下文；目标 API 已提供标准 IAM 端点。
+ * ```ts
+ * await initApi()
+ * try {
+ *   const current = await apiClient.iam.auth.currentUser()
+ *   if (!current.success) throw new Error(current.error.message)
+ * }
+ * finally { await closeApi() }
+ * ```
+ */
 export async function initApi(): Promise<void> {
+  if (closing)
+    await closing
   if (initialized)
     return
-
-  const initResult = await apiClient.init({
-    baseUrl: resolveApiBase(),
-    auth: {
-      storage: await createTokenStorage(),
-    },
+  if (initializing)
+    return initializing
+{{#if features.crypto}}
+  if (ownsCrypto)
+    await closeApi()
+{{/if}}
+  initializing = initialize().finally(() => {
+    initializing = undefined
   })
+  return initializing
+}
 
-  if (!initResult.success)
-    throw new Error(initResult.error.message)
-
+/**
+ * 在初始化屏障内装配客户端；安全存储先就绪，失败不退回明文并释放本次资源。
+ * @returns 当前客户端已初始化；由 initApi 管理并发屏障。
+ * @throws Error - 平台、所选 crypto 或 client 拒绝初始化。
+ * @throws AggregateError - 初始化失败且本次 crypto 未确认清理，保留关闭重试义务。
+ * @example 模块内部上下文；仅在初始化屏障内调用。
+ * ```ts
+ * await initialize()
+ * try {
+ *   const current = await apiClient.iam.auth.currentUser()
+ *   if (!current.success) throw new Error(current.error.message)
+ * }
+ * finally { await closeApi() }
+ * ```
+ */
+async function initialize(): Promise<void> {
+  const storage = await createTokenStorage()
+{{#if features.crypto}}
+  const transport = resolveTransport()
+  try {
+    if (transport && !crypto.isInitialized) {
+      const result = await crypto.init()
+      if (!result.success)
+        throw new Error(result.error.message)
+      ownsCrypto = true
+    }
+    const result = await apiClient.init({
+      baseUrl: resolveApiBase(),
+      auth: { storage },
+      ...(transport ? { transport } : {}),
+    })
+    if (!result.success)
+      throw new Error(result.error.message)
+    initialized = true
+  }
+  catch (error) {
+    if (ownsCrypto) {
+      try {
+        await crypto.close()
+        ownsCrypto = false
+      }
+      catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], 'Mobile API initialization and crypto cleanup failed')
+      }
+    }
+    throw error
+  }
+{{else}}
+  const result = await apiClient.init({ baseUrl: resolveApiBase(), auth: { storage } })
+  if (!result.success)
+    throw new Error(result.error.message)
   initialized = true
+{{/if}}
 }
 
+/**
+ * 等待在途初始化，先销毁客户端 transport，再释放自身初始化的 crypto。
+ * @returns 所有本次资源确认关闭；无资源或并发关闭时安全复用。
+ * @throws Error - client 或 crypto 未确认关闭；保留状态供下一次 closeApi 重试。
+ * @example 模块内部上下文；目标 API 已提供标准 IAM 端点。
+ * ```ts
+ * await initApi()
+ * try {
+ *   const current = await apiClient.iam.auth.currentUser()
+ *   if (!current.success) throw new Error(current.error.message)
+ * }
+ * finally { await closeApi() } // 先 client，再本客户端初始化的 crypto。
+ * ```
+ */
 export async function closeApi(): Promise<void> {
-  if (!initialized)
-    return
-
-  await apiClient.close()
-  initialized = false
+  closing ??= (async () => {
+    if (initializing)
+      await initializing.catch(() => undefined)
+    if (initialized) {
+      await apiClient.close()
+      initialized = false
+    }
+{{#if features.crypto}}
+    if (ownsCrypto) {
+      await crypto.close()
+      ownsCrypto = false
+    }
+{{/if}}
+  })().finally(() => {
+    closing = undefined
+  })
+  return closing
 }
 
 export { apiClient }

package/templates/apps/website/messages/ja-JP.json

@@ -0,0 +1,32 @@
+{
+  "app_title": "企業サイト",
+  "app_description": "企業の公式サイト",
+  "meta_description": "企業の公式サイト",
+  "nav_home": "ホーム",
+  "nav_about": "会社概要",
+  "nav_services": "サービス",
+  "nav_contact": "担当者",
+  "page_home_title": "ようこそ",
+  "page_home_subtitle": "専門的で信頼できる企業向けサービス",
+  "page_home_cta": "お問い合わせ",
+  "page_home_advantages": "私たちの強み",
+  "page_home_team": "専門チーム",
+  "page_home_team_desc": "長年の業界経験を持つチームです。",
+  "page_home_service": "高品質なサービス",
+  "page_home_service_desc": "総合的で質の高いサポートを提供します。",
+  "page_home_tech": "革新的な技術",
+  "page_home_tech_desc": "業界をリードする革新的な技術ソリューション。",
+  "page_about_title": "会社概要",
+  "page_about_desc": "企業情報とこれまでの歩み。",
+  "page_services_title": "サービス",
+  "page_services_item1": "サービス1",
+  "page_services_item2": "サービス2",
+  "page_services_desc": "サービスの説明。",
+  "page_contact_title": "お問い合わせ",
+  "page_contact_desc": "ご質問はお気軽にお問い合わせください。",
+  "page_contact_name": "お名前",
+  "page_contact_email": "メールアドレス",
+  "page_contact_message": "メッセージ",
+  "page_contact_submit": "送信",
+  "footer_copyright": "Copyright © {year}. All rights reserved."
+}

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

@@ -11,8 +11,8 @@
   import { page } from '$app/state'
 {{#if hasI18n}}
   import * as m from '$lib/paraglide/messages'
-  import { getLocale } from '$lib/paraglide/runtime.js'
-  import { setGlobalLocale } from '@h-ai/ui'
+  import { getLocale, setLocale } from '$lib/paraglide/runtime.js'
+  import { LanguageSwitch, setGlobalLocale } from '@h-ai/ui'
 {{/if}}
   import '../app.css'
 
@@ -37,6 +37,11 @@
   ] as const
 {{#if hasI18n}}
 
+  function handleLanguageChange(language: string) {
+    setGlobalLocale(language)
+    setLocale(language as Parameters<typeof setLocale>[0])
+  }
+
   if (browser) {
     const paraglideLocale = getLocale()
     setGlobalLocale(paraglideLocale)
@@ -64,6 +69,9 @@
         {/each}
       </ul>
     </nav>
+{{#if hasI18n}}
+    <LanguageSwitch currentLanguage={getLocale()} onchange={handleLanguageChange} />
+{{/if}}
   </header>
 
   <main class='flex-1'>

package/templates/base/e2e/app.spec.ts.hbs

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto'
 import { mkdir } from 'node:fs/promises'
 import path from 'node:path'
 import process from 'node:process'
@@ -67,7 +68,7 @@ test('configured IAM registration and password login', async ({ page, context })
 {{/if_eq}}
   const evidence = process.env.HAI_AUTH_EVIDENCE_DIR || path.resolve('test-results/auth-screenshots')
   await mkdir(evidence, { recursive: true })
-  const username = `scaf${Date.now()}`
+  const username = `scaf${randomUUID().replaceAll('-', '').slice(0, 12)}`
   const password = 'ScaffoldPassword123'
   const authUrl = '{{#if isCapacitorApp}}/{{else}}/auth/login{{/if}}'
   await page.goto(authUrl)
@@ -76,11 +77,15 @@ test('configured IAM registration and password login', async ({ page, context })
   await expect(page.locator('footer')).toBeVisible()
   await page.screenshot({ path: path.join(evidence, '{{projectName}}-login.png'), fullPage: true })
   await page.getByRole('{{#if isCapacitorApp}}button{{else}}link{{/if}}', { name: /立即注册|Register now/i }).click()
-  await expect(page.locator('input[name="username"]')).toBeVisible()
+{{#unless isCapacitorApp}}
+  await expect(page).toHaveURL(/\/auth\/register(?:\?|$)/)
+{{/unless}}
+  const registerForm = page.locator('.register-form')
+  await expect(registerForm.locator('#register-username')).toBeVisible()
   await page.screenshot({ path: path.join(evidence, '{{projectName}}-register.png'), fullPage: true })
   if (process.env.IAM_NOTIFICATION_URL) {
     // 协议弹窗留在认证页，关闭后继续填写注册表单。
-    await page.getByRole('button', { name: /用户协议|User Agreement/i, exact: true }).click()
+    await registerForm.getByRole('button', { name: /用户协议|Terms of Service/i, exact: true }).click()
     await expect(page.getByRole('dialog')).toBeVisible()
     await expect(page.getByRole('dialog').getByRole('heading', { name: 'Configured registration agreement' })).toBeVisible()
     await expect(page.locator('iframe')).toHaveCount(0)
@@ -88,11 +93,11 @@ test('configured IAM registration and password login', async ({ page, context })
     await page.keyboard.press('Escape')
     await expect(page.getByRole('dialog')).not.toBeVisible()
   }
-  await page.locator('input[name="username"]').fill(username)
-  await page.locator('input[name="email"]').fill(`${username}@example.com`)
-  await page.locator('input[type="password"]').nth(0).fill(password)
-  await page.locator('input[type="password"]').nth(1).fill(password)
-  await page.locator('button[type="submit"]').click()
+  await registerForm.locator('#register-username').fill(username)
+  await registerForm.locator('#register-email').fill(`${username}@example.com`)
+  await registerForm.locator('#register-password').fill(password)
+  await registerForm.locator('#register-confirm-password').fill(password)
+  await registerForm.locator('button[type="submit"]').click()
   await expect(page.locator('.register-form')).not.toBeVisible()
 {{#unless isCapacitorApp}}
   const me = await page.request.get('/api/auth/me')

package/templates/base/package.json.hbs

@@ -1,7 +1,7 @@
 {
   "engines": { "node": "^22.22.2 || ^24.15.0 || >=26.0.0" },
   "name": "{{projectName}}",
-  "version": "0.1.0-alpha.67",
+  "version": "0.1.0-alpha.68",
   "private": true,
   "packageManager": "pnpm@12.11.2",
   "description": "{{#if_eq appType 'admin'}}Enterprise management system built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'website'}}Enterprise website built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'h5'}}Mobile H5 app built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'api'}}REST API service built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'mobile-app'}}Mobile app built with hai Agent Framework{{/if_eq}}",
@@ -59,6 +59,9 @@
   {{#if isSvelteOnlyApp}}
     "@h-ai/api-client": "{{haiPackageSpecifier}}",
     "@h-ai/capacitor": "{{haiPackageSpecifier}}",
+{{#if features.crypto}}
+    "@h-ai/crypto": "{{haiPackageSpecifier}}",
+{{/if}}
     "@h-ai/ui": "{{haiPackageSpecifier}}"
   {{else}}
     "@h-ai/core": "{{haiPackageSpecifier}}",

package/templates/base/playwright.config.ts

@@ -1,5 +1,6 @@
 import process from 'node:process'
 import { defineConfig } from '@playwright/test'
+import { createE2eNotificationEnv, createE2eServerEnv, createE2eTransportRing } from './scripts/e2e-env.js'
 
 const DEFAULT_BASE_URL = 'http://localhost:4173'
 const baseURL = process.env.BASE_URL || DEFAULT_BASE_URL
@@ -35,9 +36,9 @@ function resolvePortFromBaseUrl(urlString: string, fallbackPort: string): string
  */
 export default defineConfig({
   testDir: './e2e',
-  fullyParallel: false,
+  fullyParallel: true,
   forbidOnly: !!process.env.CI,
-  retries: process.env.CI ? 2 : 0,
+  retries: 0,
   workers: 2,
   reporter: 'list',
   timeout: 30_000,
@@ -45,13 +46,23 @@ export default defineConfig({
   use: {
     baseURL,
     channel: 'chrome',
-    trace: 'on-first-retry',
+    trace: 'retain-on-failure',
     screenshot: 'only-on-failure',
   },
 
   webServer: {
     command: `pnpm build && pnpm preview --host ${previewHost} --port ${previewPort} --strictPort`,
-    env: { HAI_E2E: '1', BASE_URL: baseURL },
+    env: createE2eServerEnv({
+      ...createE2eNotificationEnv(),
+      HAI_CORE_ENV: 'test',
+      BASE_URL: baseURL,
+      PUBLIC_API_BASE: process.env.PUBLIC_API_BASE || '',
+      HAI_DB: JSON.stringify({ type: 'sqlite', database: `${process.env.HAI_E2E_DATA_ROOT}/app.db` }),
+      HAI_CACHE: JSON.stringify({ type: 'memory' }),
+      HAI_STORAGE: JSON.stringify({ type: 'local', root: `${process.env.HAI_E2E_DATA_ROOT}/uploads` }),
+      HAI_VECDB: JSON.stringify({ type: 'lancedb', path: `${process.env.HAI_E2E_DATA_ROOT}/vecdb` }),
+      HAI_CRYPTO_TRANSPORT_SERVERKEYRING: createE2eTransportRing(),
+    }),
     url: baseURL,
     reuseExistingServer: false,
     timeout: 180_000,

package/templates/base/src/hooks.server.ts.hbs

@@ -5,10 +5,16 @@
  */
 
 import type { Handle } from '@sveltejs/kit'
+{{#if features.cache}}
+import process from 'node:process'
+{{/if}}
 {{#if hasI18n}}
 import { paraglideMiddleware } from '$lib/paraglide/server.js'
 {{/if}}
 import { initApp } from '$lib/server/init.js'
+{{#if features.cache}}
+import { cache } from '@h-ai/cache'
+{{/if}}
 import { core } from '@h-ai/core'
 {{#if features.iam}}
 import { iam } from '@h-ai/iam'
@@ -54,16 +60,14 @@ const i18nHandle: Handle = async ({ event, resolve }) => {
   if (event.url.pathname.startsWith('/api/')) {
     const locale = event.cookies.get('PARAGLIDE_LOCALE') ?? '{{defaultLocale}}'
     event.locals.locale = locale
-    kit.i18n.setLocale(locale)
-    return resolve(event)
+    return kit.i18n.runWithLocale(locale, () => resolve(event))
   }
 
   return paraglideMiddleware(event.request, async ({ locale }) => {
     event.locals.locale = locale
-    kit.i18n.setLocale(locale)
-    return resolve(event, {
+    return kit.i18n.runWithLocale(locale, () => resolve(event, {
       transformPageChunk: ({ html }) => html.replace('%lang%', locale),
-    })
+    }))
   })
 }
 
@@ -95,7 +99,12 @@ const haiHandle = kit.createHandle({
     operations: () => iam.auth,
   },
 {{/if}}
-  rateLimit: { windowMs: 60000, maxRequests: 200 },
+{{#if features.cache}}
+  rateLimit: { windowMs: 60000, maxRequests: 200, store: kit.middleware.createCacheRateLimitStore(cache, { namespace: '{{projectName}}', allowMemory: process.env.NODE_ENV !== 'production' || process.env.HAI_E2E === '1' }) },
+{{else}}
+  // 未选择cache能力时不启用限流；启用前须接入共享原子store。
+  rateLimit: false,
+{{/if}}
   logging: { logBody: false },
   onError: (error: unknown, _event) => {
     core.logger.error('Request error:', { error })