@h-ai/cli 1.0.0-beta.2 → 1.0.0-beta.21

package/templates/apps/api/apps/{{projectName}}-serv/tests/service.test.ts.hbs

@@ -4,17 +4,29 @@ import type { AddressInfo } from 'node:net'
 import { mkdtempSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-{{#if features.ai}}import { ai } from '@h-ai/ai'
-{{/if}}import { apiClient } from '@h-ai/api-client'
-{{#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'
-{{/if}}{{#if features.db}}import { reldb } from '@h-ai/reldb'
-{{/if}}import { serv } from '@h-ai/serv'
-{{#if features.storage}}import { storage } from '@h-ai/storage'
-{{/if}}{{#if features.vecdb}}import { vecdb } from '@h-ai/vecdb'
-{{/if}}import { {{api.contractExportName}} } from '{{api.contractPackageName}}'
-import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+{{#if features.ai}}
+import { ai } from '@h-ai/ai'
+{{/if}}
+import { apiClient } from '@h-ai/api-client'
+{{#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'
+{{/if}}
+{{#if features.db}}
+import { reldb } from '@h-ai/reldb'
+{{/if}}
+import { serv } from '@h-ai/serv'
+{{#if features.storage}}
+import { storage } from '@h-ai/storage'
+{{/if}}
+{{#if features.vecdb}}
+import { vecdb } from '@h-ai/vecdb'
+{{/if}}
+import { {{api.contractExportName}} } from '{{api.contractPackageName}}'
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
 
 import { {{api.serviceAppFactoryName}} } from '../src/app.js'
 
@@ -23,10 +35,12 @@ let baseUrl = ''
 let client: ReturnType<typeof apiClient.create<typeof {{api.contractExportName}}>>
 let server: ReturnType<typeof serv.listen>
 let servConfig: ServConfig
-{{#if features.storage}}let storageRoot = ''
-{{/if}}{{#if features.vecdb}}let vecdbRoot = ''
+{{#if features.storage}}
+let storageRoot = ''
+{{/if}}
+{{#if features.vecdb}}
+let vecdbRoot = ''
 {{/if}}
-
 {{#if features.iam}}
 function uniqueUser(prefix = 'api') {
   const suffix = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`.slice(-8)
@@ -40,10 +54,14 @@ function uniqueUser(prefix = 'api') {
 
 beforeAll(async () => {
   tempRoot = mkdtempSync(join(tmpdir(), '{{projectName}}-service-test-'))
-{{#if features.storage}}  storageRoot = join(tempRoot, 'storage')
-{{/if}}{{#if features.vecdb}}  vecdbRoot = join(tempRoot, 'vecdb')
+{{#if features.storage}}
+  storageRoot = join(tempRoot, 'storage')
+{{/if}}
+{{#if features.vecdb}}
+  vecdbRoot = join(tempRoot, 'vecdb')
 {{/if}}
 
+  vi.stubEnv('HAI_SERV_CORS_NATIVEORIGINS', undefined)
   core.init({
     configDir: './config',
     logging: { level: 'warn' },
@@ -54,27 +72,32 @@ beforeAll(async () => {
   const dbResult = await reldb.init({ type: 'sqlite', database: ':memory:' })
   if (!dbResult.success)
     throw new Error(`reldb: ${dbResult.error.message}`)
-{{/if}}{{#if features.cache}}
+{{/if}}
+{{#if features.cache}}
 
   const cacheResult = await cache.init({ type: 'memory' })
   if (!cacheResult.success)
     throw new Error(`cache: ${cacheResult.error.message}`)
-{{/if}}{{#if features.vecdb}}
+{{/if}}
+{{#if features.vecdb}}
 
   const vecdbResult = await vecdb.init({ type: 'lancedb', path: vecdbRoot })
   if (!vecdbResult.success)
     throw new Error(`vecdb: ${vecdbResult.error.message}`)
-{{/if}}{{#if features.iam}}
+{{/if}}
+{{#if features.iam}}
 
   const iamResult = await iam.init({})
   if (!iamResult.success)
     throw new Error(`iam: ${iamResult.error.message}`)
-{{/if}}{{#if features.storage}}
+{{/if}}
+{{#if features.storage}}
 
   const storageResult = await storage.init({ type: 'local', root: storageRoot })
   if (!storageResult.success)
     throw new Error(`storage: ${storageResult.error.message}`)
-{{/if}}{{#if features.ai}}
+{{/if}}
+{{#if features.ai}}
 
   const aiResult = await ai.init({})
   if (!aiResult.success)
@@ -82,8 +105,7 @@ beforeAll(async () => {
 {{/if}}
 
   const app = {{api.serviceAppFactoryName}}({
-    transport: 'disabled',{{#if features.iam}}
-    refreshCookie: 'disabled',{{/if}}
+    transport: 'disabled',
   })
   const listening = new Promise<AddressInfo>((resolve) => {
     server = serv.listen(app, {
@@ -98,7 +120,11 @@ beforeAll(async () => {
   client = apiClient.create({{api.contractExportName}})
   const initResult = await client.init({
     baseUrl: `${baseUrl}${servConfig.http.apiPrefix}`,
-    auth: { storage: apiClient.tokenStorage.memory() },
+    clientName: 'hai-mobile-app',
+    headers: { 'origin': 'capacitor://localhost', 'x-hai-token-transport': 'body' },
+    auth: {
+      storage: apiClient.tokenStorage.memory(),
+    },
   })
   if (!initResult.success)
     throw new Error(`client.init: ${initResult.error.message}`)
@@ -107,13 +133,26 @@ beforeAll(async () => {
 afterAll(async () => {
   await client?.close()
   await server?.close()
-{{#if features.ai}}  await ai.close()
-{{/if}}{{#if features.storage}}  await storage.close()
-{{/if}}{{#if features.iam}}  await iam.close()
-{{/if}}{{#if features.vecdb}}  await vecdb.close()
-{{/if}}{{#if features.cache}}  await cache.close()
-{{/if}}{{#if features.db}}  await reldb.close()
-{{/if}}  rmSync(tempRoot, { recursive: true, force: true })
+{{#if features.ai}}
+  await ai.close()
+{{/if}}
+{{#if features.storage}}
+  await storage.close()
+{{/if}}
+{{#if features.iam}}
+  await iam.close()
+{{/if}}
+{{#if features.vecdb}}
+  await vecdb.close()
+{{/if}}
+{{#if features.cache}}
+  await cache.close()
+{{/if}}
+{{#if features.db}}
+  await reldb.close()
+{{/if}}
+  rmSync(tempRoot, { recursive: true, force: true })
+  vi.unstubAllEnvs()
 })
 
 describe('{{api.servPackageName}}', () => {
@@ -132,7 +171,12 @@ describe('{{api.servPackageName}}', () => {
     expect(result.success).toBe(true)
     if (result.success) {
       const config = core.config.getOrThrow<CoreConfig>('core')
-      expect(result.data).toMatchObject({ name: config.name, version: config.version, env: config.env, defaultLocale: config.defaultLocale })
+      expect(result.data).toMatchObject({
+        name: config.name,
+        version: config.version,
+        env: config.env,
+        defaultLocale: config.defaultLocale,
+      })
       expect(typeof result.data.transportEnabled).toBe('boolean')
     }
   })
@@ -142,8 +186,37 @@ describe('{{api.servPackageName}}', () => {
 
     expect(result.success).toBe(false)
   })
-
 {{#if features.iam}}
+  it.each([
+    ['capacitor://localhost', 'hai-mobile-app'],
+    ['https://localhost', 'hai-mobile-app'],
+    ['http://tauri.localhost', 'hai-desktop-app'],
+    ['https://tauri.localhost', 'hai-desktop-app'],
+    ['tauri://localhost', 'hai-desktop-app'],
+  ])('refreshes an expired access token at the default native Origin %s', async (origin, clientName) => {
+    const native = apiClient.create({{api.contractExportName}})
+    try {
+      expect((await native.init({
+        baseUrl: `${baseUrl}${servConfig.http.apiPrefix}`,
+        clientName,
+        headers: { 'origin': origin, 'x-hai-token-transport': 'body' },
+        auth: {
+          storage: apiClient.tokenStorage.memory(),
+        },
+      })).success).toBe(true)
+      const registration = await apiClient.createAuthActions(native).register(uniqueUser('refresh'))
+      expect(registration.success).toBe(true)
+      if (!registration.success)
+        return
+      expect(registration.data.tokens.refreshToken).toBeTruthy()
+      await native.auth.setTokens({ ...registration.data.tokens, accessToken: 'expired-access-for-test' })
+      expect((await native.iam.auth.currentUser()).success).toBe(true)
+    }
+    finally {
+      await native.close()
+    }
+  })
+
   it('registers a user and returns authenticated echo context', async () => {
     const user = uniqueUser('svc')
     const authActions = apiClient.createAuthActions(client)

package/templates/apps/api/apps/{{projectName}}-serv/tsup.config.ts.hbs

@@ -6,7 +6,9 @@ import { resolveBuildMetadata } from '../../scripts/build-metadata.js'
 const buildMetadata = resolveBuildMetadata(fileURLToPath(new URL('.', import.meta.url)))
 
 export default defineConfig({
-  define: { __HAI_BUILD_METADATA__: JSON.stringify(buildMetadata) },
+  define: {
+    __HAI_BUILD_METADATA__: JSON.stringify(buildMetadata),
+  },
   async onSuccess() {
     await writeFile(new URL('./dist/build-metadata.json', import.meta.url), JSON.stringify(buildMetadata))
   },

package/templates/apps/api/apps/{{projectName}}-serv/vitest.config.ts.hbs

@@ -3,7 +3,9 @@ import { defineConfig } from 'vitest/config'
 import { resolveBuildMetadata } from '../../scripts/build-metadata.js'
 
 export default defineConfig({
-  define: { __HAI_BUILD_METADATA__: JSON.stringify(resolveBuildMetadata(fileURLToPath(new URL('.', import.meta.url)))) },
+  define: {
+    __HAI_BUILD_METADATA__: JSON.stringify(resolveBuildMetadata(fileURLToPath(new URL('.', import.meta.url)))),
+  },
   test: {
     globals: true,
     environment: 'node',

package/templates/apps/api/e2e/api-serv.spec.ts.hbs

@@ -16,7 +16,9 @@ test.beforeAll(async () => {
   const result = await client.init({
     baseUrl: `${process.env.BASE_URL || 'http://127.0.0.1:3000'}${API_PREFIX}`,
 {{#if features.iam}}
-    auth: { storage: apiClient.tokenStorage.memory() },
+    auth: {
+      storage: apiClient.tokenStorage.memory(),
+    },
 {{/if}}
 {{#if features.crypto}}
     transport: { crypto },
@@ -105,9 +107,24 @@ test('feedback intake is idempotent and creator can append evidence without admi
   expect(duplicate.success).toBe(true)
   if (duplicate.success)
     expect(duplicate.data.id).toBe(created.data.id)
-  const evidence = await client.feedback.reports.appendEvidence({ id: created.data.id, evidence: [{ id: 'event-1', source: 'api-test', sequence: 1, kind: 'business', timestamp: Date.now(), data: { action: 'api-feedback' } }] })
+  const evidence = await client.feedback.reports.appendEvidence({
+    id: created.data.id,
+    evidence: [
+      {
+        id: 'event-1',
+        source: 'api-test',
+        sequence: 1,
+        kind: 'business',
+        timestamp: Date.now(),
+        data: { action: 'api-feedback' },
+      },
+    ],
+  })
   expect(evidence.success).toBe(true)
-  expect((await client.feedback.reports.completeCollection({ id: created.data.id, missing: ['browser-not-applicable'] })).success).toBe(true)
+  expect((await client.feedback.reports.completeCollection({
+    id: created.data.id,
+    missing: ['browser-not-applicable'],
+  })).success).toBe(true)
   expect((await client.feedback.reports.list({})).success).toBe(false)
 })
 {{/if}}

package/templates/apps/api/e2e/capture-evidence.ts.hbs

@@ -15,7 +15,10 @@ export default async function captureEvidence() {
     expect(response?.status()).toBe(200)
     await expect(page.locator('body')).toContainText('ok')
     await mkdir(evidence, { recursive: true })
-    await page.screenshot({ path: path.join(evidence, '{{projectName}}-health.png'), fullPage: true })
+    await page.screenshot({
+      path: path.join(evidence, '{{projectName}}-health.png'),
+      fullPage: true,
+    })
   }
   finally {
     await browser.close()

package/templates/apps/api/eslint.config.js.hbs

@@ -3,7 +3,9 @@ import { haiQualityConfig } from './eslint-rules.js'
 
 export default antfu({
   // unused-imports 使用 TS 规则，JS 同样使用 TS parser 以保持 scope 契约一致。
-  typescript: { files: [GLOB_SRC] },
+  typescript: {
+    files: [GLOB_SRC],
+  },
   formatters: true,
   ignores: [
     '**/dist/**',

package/templates/apps/api/images/serv.Dockerfile.hbs

@@ -1,6 +1,5 @@
-FROM node:24.22.1-bookworm-slim AS build
-ARG SQLITE_PREBUILD_MIRROR=
-ENV npm_config_better_sqlite3_binary_host_mirror=$SQLITE_PREBUILD_MIRROR
+ARG HAI_NODE_IMAGE=node:24.22.1-bookworm-slim
+FROM ${HAI_NODE_IMAGE} AS build
 
 ENV PNPM_HOME=/pnpm
 ENV PATH=$PNPM_HOME:$PATH
@@ -8,19 +7,25 @@ ENV CI=true
 ENV ONNXRUNTIME_NODE_INSTALL_CUDA=skip
 WORKDIR /workspace
 
-RUN corepack enable && corepack prepare pnpm@12.11.2 --activate && pnpm config set store-dir /pnpm/store
+ARG HAI_NPM_REGISTRY=https://registry.npmjs.org
+ARG COREPACK_NPM_REGISTRY=$HAI_NPM_REGISTRY
+ARG npm_config_registry=$HAI_NPM_REGISTRY
+ARG pnpm_config_registry=$HAI_NPM_REGISTRY
+RUN node -e "const p=process.env.HTTPS_PROXY||process.env.HTTP_PROXY;if(p){const u=new URL(p);const s=require('node:net').connect({host:u.hostname,port:Number(u.port||(u.protocol==='https:'?443:80))});s.setTimeout(3000);s.on('connect',()=>s.end());const fail=()=>{process.stderr.write('Build proxy is unreachable from the container. Check the host address and proxy listener.\\n');process.exit(1)};s.on('error',fail);s.on('timeout',fail)}" && corepack enable && corepack prepare pnpm@12.11.2 --activate && pnpm config set store-dir /pnpm/store
 COPY pnpm-lock.yaml pnpm-workspace.yaml ./
 COPY images/dependencies/ ./
-RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm fetch --ignore-scripts
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm fetch --reporter=append-only --ignore-scripts
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm install --reporter=append-only --offline --frozen-lockfile --ignore-scripts
 COPY . .
-RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm install --offline --frozen-lockfile --ignore-scripts
 ARG HAI_BUILD_ID=
 ARG HAI_BUILD_COMMIT=unknown
 RUN HAI_BUILD_ID="$HAI_BUILD_ID" HAI_BUILD_COMMIT="$HAI_BUILD_COMMIT" pnpm compile
-RUN --mount=type=cache,id={{projectName}}-sqlite,target=/root/.npm/_prebuilds if [ -d node_modules/better-sqlite3 ]; then cd node_modules/better-sqlite3; for attempt in 1 2 3; do node -e "require('node:child_process').execFileSync(process.execPath,[require.resolve('prebuild-install/bin.js'),'--verbose'],{stdio:'inherit'})" && break; [ "$attempt" = 3 ] && exit 1; sleep 3; done; fi
-RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store --mount=type=cache,id={{projectName}}-sqlite,target=/root/.npm/_prebuilds pnpm pm deploy --filter {{api.servPackageName}} --prod /prod/app
+# SQLite 13 的原生二进制随 npm 包交付，在构建时验证实际加载。
+RUN if [ -d node_modules/better-sqlite3 ]; then node -e "const Database=require('better-sqlite3');const db=new Database(':memory:');db.prepare('SELECT 1').get();db.close()"; fi
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm pm deploy --filter {{api.servPackageName}} --prod /prod/app
+RUN rm -f /prod/app/README* && find /prod/app/dist -type f \( -name '*.map' -o -name '*.d.ts' -o -name '*.d.mts' -o -name '*.d.cts' \) -delete
 
-FROM node:24.22.1-bookworm-slim AS runtime-base
+FROM ${HAI_NODE_IMAGE} AS runtime-base
 
 ENV NODE_ENV=production
 ENV HOST=0.0.0.0
@@ -33,5 +38,5 @@ RUN mkdir -p /app/data && chown node:node /app/data
 USER node
 EXPOSE 3000
 HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
-  CMD node -e "fetch('http://127.0.0.1:'+process.env.PORT+'/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+  CMD node -e "(async () => { try { const { core } = await import('@h-ai/core'); const { ServConfigSchema } = await import('@h-ai/serv'); core.init({ configDir: './config', configSchemas: { serv: ServConfigSchema } }); const { server, http } = ServConfigSchema.parse(core.config.getOrThrow('serv')); if (http.health === false) process.exit(0); const response = await fetch('http://127.0.0.1:' + server.port + http.health.path, { signal: AbortSignal.timeout(4000) }); process.exit(response.ok ? 0 : 1); } catch { process.exit(1); } })()"
 CMD ["node", "dist/index.js"]

package/templates/apps/api/playwright.config.ts.hbs

@@ -24,7 +24,9 @@ function resolvePortFromBaseUrl(urlString: string, fallbackPort: string): string
       return url.port
     }
 
-    return url.protocol === 'https:' ? '443' : '80'
+    return url.protocol === 'https:'
+      ? '443'
+      : '80'
   }
   catch {
     return fallbackPort
@@ -46,22 +48,24 @@ export default defineConfig({
     trace: 'retain-on-failure',
     screenshot: 'only-on-failure',
   },
-  webServer: [{
-    name: '{{api.servPackageName}}',
-    command: 'pnpm --filter {{api.servPackageName}} exec node dist/index.js',
-    env: createE2eServerEnv({
-      ...createE2eNotificationEnv(),
-      HAI_CORE_ENV: 'test',
-      HAI_DB: JSON.stringify({ type: 'sqlite', database: `${process.env.HAI_E2E_DATA_ROOT}/api.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(),
-      HOST: serviceHost,
-      PORT: servicePort,
-    }),
-    url: `${baseURL}/health`,
-    reuseExistingServer: false,
-    timeout: 120_000,
-  }],
+  webServer: [
+    {
+      name: '{{api.servPackageName}}',
+      command: 'pnpm --filter {{api.servPackageName}} exec node dist/index.js',
+      env: createE2eServerEnv({
+        ...createE2eNotificationEnv(),
+        HAI_CORE_ENV: 'test',
+        HAI_DB: JSON.stringify({ type: 'sqlite', database: `${process.env.HAI_E2E_DATA_ROOT}/api.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(),
+        HOST: serviceHost,
+        PORT: servicePort,
+      }),
+      url: `${baseURL}/health`,
+      reuseExistingServer: false,
+      timeout: 120_000,
+    },
+  ],
 })

package/templates/apps/api/pnpm-workspace.yaml.hbs

@@ -1,5 +1,5 @@
 {{! @skipIfEmpty }}
-shellEmulator: true
+minimumReleaseAgeExcludePrune: true
 
 trustPolicy: no-downgrade
 # 上游构建工具仍要求 4.x；4.0.3 tarball 已核对原 lockfile 的 SHA-512。
@@ -8,33 +8,44 @@ trustPolicyExclude:
 
 # pnpm 12 配置；原生依赖仅运行明确列出的安装脚本。
 nodeLinker: hoisted
-allowBuilds:
-  cpu-features: true
-  onnxruntime-node: true
-  protobufjs: true
-  ssh2: true
-  vue-demi: true
-  better-sqlite3: true
-  esbuild: true
-  core-js: false
+shellEmulator: true
 
+packages:
+  - apps/*
+
+# 构建与浏览器依赖的安全修复；版本与框架工作区同步维护。
 overrides:
-  "@ai-sdk/provider-utils@>=4.0.0 <4.0.33": 4.0.57
+  '@ai-sdk/provider-utils@>=4.0.0 <4.0.33': 4.0.57
+  '@types/node': {{versions.nodeTypes}}
+  body-parser@>=2 <2.4.0: 2.4.0
   cookie@<0.7.0: 0.7.2
+  dompurify@>=3 <3.4.17: 3.4.17
   esbuild@<0.28.1: 0.28.2
+  fast-uri@>=3 <3.1.9: 3.1.9
+  follow-redirects@>=1.16.0 <1.16.2: 1.16.2
+  glob@>=9 <=14.0.1: 14.0.4
+  ip-address@<=10.7.3: 10.7.6
   katex@<0.18.2: 0.18.10
+  minimatch@>=7 <11.0.1: 11.0.5
+  parse5@>=8 <8.1.0: 8.1.0
+  qs@>=6.7 <6.16.1: 6.17.1
+  runed@<0.38.0: 0.38.0
   sharp@<0.35.5: 0.35.5
   tinypool@<2.1.2: 2.2.0
-  '@qdrant/js-client-rest>undici': 7.30.0
   xcode>uuid: 11.1.1
-  "@types/node": "{{versions.nodeTypes}}"
 
-packages:
-  - apps/*
+allowBuilds:
+  core-js: false
+  cpu-features: true
+  esbuild: true
+  onnxruntime-node: true
+  protobufjs: true
+  ssh2: true
+  vue-demi: true
 
 {{#if useCatalogProtocol}}
 catalog:
 {{#each haiCatalogPackages}}
-  '{{@key}}': {{this}}
+  {{{yaml @key this}}}
 {{/each}}
 {{/if}}

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

@@ -23,3 +23,13 @@ tmp
 # 仅保留公共基础 .env；分环境配置、私有覆盖及已有交付包不进入构建上下文。
 **/.env.*
 **/.hai
+# 部署证书和测试材料不进入镜像构建上下文。
+**/*.pem
+**/*.key
+**/*.p12
+**/*.pfx
+**/tests
+**/e2e
+**/*.test.*
+**/*.spec.*
+docs

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

@@ -3,8 +3,13 @@ node_modules
 build
 dist
 .turbo
-android
-ios
+**/android/.gradle/
+**/android/**/build/
+**/ios/Pods/
+**/ios/App/Pods/
+*.keystore
+*.jks
+*.p12
 **/src/lib/paraglide
 **/src-tauri/gen/
 **/src-tauri/target/

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

@@ -4,6 +4,8 @@
 
 ## 简介
 
+`android` / `ios` 是需要维护的原生工程，应提交 Git；签名秘密单独忽略。普通 `clean` 保留这些目录，只清除构建产物。
+
 App/H5 前端工程，复用 shared 的响应式 mini 后台，使用 Svelte 5 + Vite + Capacitor，可输出 Web 预览并同步 Android / iOS 原生工程。
 
 ## 核心功能清单
@@ -14,8 +16,12 @@ App/H5 前端工程，复用 shared 的响应式 mini 后台，使用 Svelte 5 +
 
 ## 使用入门
 
+`capacitor.config.ts` 的 `appName` 动态读取 `packages/{{fullstack.servPackageName}}/config/_core.yml` 的 `name`，环境文件从工程根加载，支持 `HAI_CORE_NAME` 及 Core 的统一优先级。正式打包默认 `prod`，进程 `HAI_CORE_ENV` 可选择模式。名称在原生构建时固定；已有 Android/iOS 工程还需同步平台显示名（Android `strings.xml` 的 `app_name` / `title_activity_main`，iOS `CFBundleDisplayName`），再重新打包。
+
 ### i18n 与 shared 协同
 
+先从工程根安装依赖并启动Serv。浏览器预览输入有效账号应进入共享界面，原生包还要配置设备真实可达API。上传头像的输入为允许类型且不超过512KiB的图片，输出为服务端生成资源标识和展示结果；不把本机任意路径当上传key。主题/语言改变后应在重新登录时恢复。
+
 - 本端页面文案：`messages/{locale}.json` + `project.inlang/settings.json`
 - 共享 Shell/主题/语言/API：`packages/{{fullstack.sharedPackageName}}`
 - 语言切换通过 shared runtime 与本端 `src/lib/paraglide/runtime.js` 同步。
@@ -35,25 +41,21 @@ pnpm --filter {{projectName}}-app build
 # 同步原生工程；首次使用前按需执行 cap:add:android / cap:add:ios
 pnpm --filter {{projectName}}-app cap:sync
 
-# Android / iOS 原生打包
-pnpm --filter {{projectName}}-app cap:build:android:debug
-pnpm --filter {{projectName}}-app package:android
-pnpm --filter {{projectName}}-app package:ios
+# 工程根的原生打包入口
+pnpm build --target app --platform android --runtime auto --debug
+pnpm build --target app --platform android --runtime auto
+pnpm build --target app --platform ios
 ```
 
 本地开发通过根 `.env` 的 `PUBLIC_API_BASE` 配置代理。原生打包前，在本端 `public/runtime-config.js` 中设置 `globalThis.__HAI_PUBLIC_CONFIG__ = { apiBase: 'https://api.example.com/api/v1' }`，再编译并同步原生工程；这里只能放公开地址，不能放密钥。Android 模拟器访问宿主机通常使用 `http://10.0.2.2:3000/api/v1`。
 
-发布入口实际调用 hai build --target app，缺平台工程、工具链、签名配置或新的 APK/IPA 均失败。package 默认 Android；iOS 必须在 macOS/Xcode 上执行。CAPACITOR_SERVER_URL 仅开发使用，发行打包过滤并核验不进入原生配置。调试 APK 命令为 Windows Gradle 调试入口，不作为发行成功证据。
-
-### IAM 认证配置
-
-服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。Memory 仅用于本地开发和显式测试；生产环境即使只有一个实例，也须使用框架支持的共享数据库与 Redis，并按工程根 README 配置写入路由和传输会话。
+Android 容器会安装依赖、编译 workspace 并打包。调试时可临时生成缺失的 Android 工程。发布时使用已有 Android 工程和私有签名配置，见 [Android 容器打包](../../.agents/skills/hai-capacitor/reference.md#android-容器打包)。iOS 使用 macOS/Xcode 和相应签名。`CAPACITOR_SERVER_URL` 仅供开发热更新。成功后 CLI 打印 `.hai/build/app/<平台>/<构建类型>/build-{{projectName}}-app-<平台>-<类型>-YYYYMMDD-HHmmss-<随机串>-<版本>/` 中的安装包路径；APK 如 `{{projectName}}-android-debug-<版本>.apk`，使用工程标识，显示名仍取 Core。
 
-LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IAM 服务端 workspace 安装 ldapts，再配置 login.ldap 与连接信息。自定义 onOtpSendEmail/onOtpSendSms/onPasswordResetRequest 回调可独立于 Reach 使用，投递失败须拒绝 Promise；回调第三参数 context 提供 expiresAt/idempotencyKey，发送服务按稳定键持久化去重，异常/超时为结果未知且不自动重发。协议在 Modal 显示；LoginForm/RegisterForm 提供 header/extraFields/footer，AuthPanel 透传 loginHeader/loginFields/loginFooter 和 registerHeader/registerFields/registerFooter。配置及例子见生成项目的 hai-iam/hai-ui skills。
+### 认证与模块导航
 
-协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
+认证方式、注册、密码策略、协议与品牌由Serv的 `_iam.yml` 控制。前端只接收安全公开配置，使用共享AuthPanel和加密typed client；服务端再次核验权限。LDAP、通知回调、用途证明和会话限制在服务端接入，不把私密配置复制到客户端。
 
-完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
+所有前端共用的偏好、认证存储、表单、审计与帮助行为见[共享工作区](../../packages/{{fullstack.sharedPackageName}}/README.md)，详细配置见[生成应用IAM技能](../../.agents/skills/hai-iam/reference.md)。
 
 启用反馈时，shared SDK 负责图片预览/比例标注/导出轮询；原生保存使用 Filesystem 缓存与 Share，完成/取消清理临时文件。首次添加 iOS 平台后按 Filesystem 插件要求配置 PrivacyInfo.xcprivacy。
 

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

@@ -1,20 +1,22 @@
 {{! @skipIfEmpty }}
 {{#if fullstack.frontends.app}}
 import type { CapacitorConfig } from '@capacitor/cli'
+import { resolve } from 'node:path'
 import process from 'node:process'
+import { resolveNativeName } from '../../scripts/native-name.mjs'
 
+const envDir = resolve(process.cwd(), '../..')
 const config: CapacitorConfig = {
   appId: 'com.hai.{{fullstack.nativeAppIdSegment}}.app',
-  appName: {{jsString fullstack.appName}},
+  appName: resolveNativeName(envDir, resolve(envDir, 'packages/{{fullstack.servPackageName}}/config/_core.yml')),
   webDir: 'dist',
   server: process.env.NODE_ENV === 'production'
     ? undefined
     : {
-        // 仅用于 Capacitor live reload 前端页面；API 地址由前端配置或 shared client 参数控制。
+      // 仅用于 Capacitor live reload 前端页面；API 地址由前端配置或 shared client 参数控制。
         url: process.env.CAPACITOR_SERVER_URL,
         cleartext: process.env.CAPACITOR_SERVER_URL?.startsWith('http://') ?? false,
       },
 }
-
 export default config
 {{/if}}

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

@@ -5,9 +5,17 @@ import { haiQualityConfig } from '../../eslint-rules.js'
 
 export default antfu({
   // unused-imports 使用 TS 规则，JS 同样使用 TS parser 以保持 scope 契约一致。
-  typescript: { files: [GLOB_SRC] },
+  typescript: {
+    files: [GLOB_SRC],
+  },
   formatters: true,
-  ignores: ['**/build/**', '**/dist/**', '**/*.d.ts', '**/project.inlang/**', '**/src/lib/paraglide/**'],
+  ignores: [
+    '**/build/**',
+    '**/dist/**',
+    '**/*.d.ts',
+    '**/project.inlang/**',
+    '**/src/lib/paraglide/**',
+  ],
   svelte: true,
 }, haiQualityConfig, {
   files: ['**/*.svelte'],

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

@@ -23,7 +23,7 @@
     "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",
+    "clean": "rimraf dist build .turbo src/lib/paraglide",
     "cap:add:android": "cap add android",
     "cap:add:ios": "cap add ios",
     "cap:sync": "pnpm build && cap sync",

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

@@ -30,7 +30,13 @@
     apiOptions = {
       clientName: '{{projectName}}-app',
       terminalType: 'app',
-      ...(capacitor.isNative() ? { requireApiBase: true, tokenStorage: createCapacitorTokenStorage(), headers: { 'X-HAI-Token-Transport': 'body' } } : {}),
+      ...(capacitor.isNative()
+        ? {
+          requireApiBase: true,
+          tokenStorage: createCapacitorTokenStorage(),
+          headers: { 'X-HAI-Token-Transport': 'body' },
+        }
+        : {}),
     }
   }
   onMount(() => {
@@ -42,7 +48,9 @@
       })
     }
   })
-  useToastFeedback(() => startupFailed ? messages.operation_failed() : '')
+  useToastFeedback(() => startupFailed
+    ? messages.operation_failed()
+    : '')
 </script>
 
 {#if startupFailed}