@h-ai/cli 0.1.0-alpha.19 → 0.1.0-alpha.21

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

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {},
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "tests"
+  ]
+}

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

@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: { index: 'src/index.ts' },
+  format: ['esm'],
+  target: 'node22',
+  sourcemap: true,
+  clean: true,
+  dts: true,
+  external: ['@h-ai/api-contract', 'zod'],
+})

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

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+  },
+})

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

@@ -0,0 +1,17 @@
+# {{api.servicePackageName}}
+
+{{projectName}} API service 包，负责模块初始化、procedure 装配与 HTTP 入口。
+
+## 常用命令
+
+```bash
+pnpm --filter {{api.servicePackageName}} dev
+pnpm --filter {{api.servicePackageName}} test
+```
+
+## 关键目录
+
+- `config/`：service 配置
+- `src/app.ts`：HTTP App 装配
+- `src/lib/server/init.ts`：模块初始化与关闭
+- `src/server/procedures/`：应用级 procedures

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

@@ -0,0 +1,19 @@
+# =============================================================================
+# {{projectName}} API Service - 应用配置
+# =============================================================================
+
+name: {{projectName}} API Service
+version: 0.1.0
+env: ${HAI_ENV:development}
+debug: false
+
+defaultLocale: {{defaultLocale}}
+supportedLocales:
+{{#if_eq defaultLocale 'en-US'}}  - en-US
+  - zh-CN
+{{else}}  - zh-CN
+  - en-US
+{{/if_eq}}
+
+features:
+  apiAccess: true

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

@@ -0,0 +1,26 @@
+# =============================================================================
+# {{projectName}} API Service - Serv / HTTP 入口配置
+# =============================================================================
+
+http:
+  apiPrefix: /api/v1
+  openapi:
+    path: /openapi.json
+  docs:
+    path: /docs
+  health:
+    path: /health
+    readyPath: /ready
+  rpc: false
+
+{{#if features.crypto}}transport:
+  keyExchangePath: /_hai/key-exchange
+  excludePaths:
+    - /health
+    - /ready
+    - /openapi.json
+    - /docs
+    - /_hai/scalar.js
+  maxClients: 10000
+{{else}}transport: false
+{{/if}}

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

@@ -0,0 +1,55 @@
+{
+  "name": "{{api.servicePackageName}}",
+  "type": "module",
+  "version": "0.1.0",
+  "private": true,
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rimraf dist .turbo",
+    "dev": "pnpm build && node dist/index.js",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@h-ai/core": "{{haiPackageSpecifier}}",
+    "@h-ai/serv": "{{haiPackageSpecifier}}",
+    "{{api.contractPackageName}}": "workspace:*"{{#if features.ai}},
+    "@h-ai/ai": "{{haiPackageSpecifier}}"{{/if}}{{#if features.audit}},
+    "@h-ai/audit": "{{haiPackageSpecifier}}"{{/if}}{{#if features.cache}},
+    "@h-ai/cache": "{{haiPackageSpecifier}}"{{/if}}{{#if features.crypto}},
+    "@h-ai/crypto": "{{haiPackageSpecifier}}"{{/if}}{{#if features.datapipe}},
+    "@h-ai/datapipe": "{{haiPackageSpecifier}}"{{/if}}{{#if features.deploy}},
+    "@h-ai/deploy": "{{haiPackageSpecifier}}"{{/if}}{{#if features.iam}},
+    "@h-ai/iam": "{{haiPackageSpecifier}}"{{/if}}{{#if features.payment}},
+    "@h-ai/payment": "{{haiPackageSpecifier}}"{{/if}}{{#if features.reach}},
+    "@h-ai/reach": "{{haiPackageSpecifier}}"{{/if}}{{#if features.db}},
+    "@h-ai/reldb": "{{haiPackageSpecifier}}"{{/if}}{{#if features.scheduler}},
+    "@h-ai/scheduler": "{{haiPackageSpecifier}}"{{/if}}{{#if features.storage}},
+    "@h-ai/storage": "{{haiPackageSpecifier}}"{{/if}}{{#if features.vecdb}},
+    "@h-ai/vecdb": "{{haiPackageSpecifier}}"{{/if}}
+  },
+  "devDependencies": {
+    "@h-ai/api-client": "{{haiPackageSpecifier}}",
+    "@types/node": "{{api.packageSpecifiers.nodeTypes}}",
+    "rimraf": "{{api.packageSpecifiers.rimraf}}",
+    "tsup": "{{api.packageSpecifiers.tsup}}",
+    "typescript": "{{api.packageSpecifiers.typescript}}",
+    "vitest": "{{api.packageSpecifiers.vitest}}"
+  }
+}

package/templates/apps/api/apps/{{projectName}}-service/src/app.ts.hbs

@@ -0,0 +1,98 @@
+import type { ServConfig } from '@h-ai/serv'
+import { core } from '@h-ai/core'
+{{#if features.crypto}}import { crypto, TRANSPORT_PROTOCOL } from '@h-ai/crypto'
+{{/if}}{{#if features.iam}}import { iam } from '@h-ai/iam'
+{{/if}}import { serv } from '@h-ai/serv'
+import { {{api.contractExportName}} } from '{{api.contractPackageName}}'
+import pkg from '../package.json' with { type: 'json' }
+import { {{api.serviceProceduresFactoryName}} } from './server/procedures/index.js'
+
+const startedAt = Date.now()
+
+interface CreateApiServiceAppOptions {
+  transport?: 'config' | 'disabled'
+  refreshCookie?: 'enabled' | 'disabled'
+}
+
+const LOOPBACK_ORIGIN_RE = /^https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\])(?::\d+)?$/
+const WEBVIEW_ORIGINS = new Set([
+  'capacitor://localhost',
+  'http://localhost',
+  'https://tauri.localhost',
+  'tauri://localhost',
+])
+const DEFAULT_CORS_ALLOWED_HEADERS = [
+  'Authorization',
+  'Content-Type',
+{{#if features.crypto}}  TRANSPORT_PROTOCOL.CLIENT_ID_HEADER,
+  TRANSPORT_PROTOCOL.ENCRYPTED_HEADER,
+{{/if}}  'X-Hai-Locale',
+  'X-Request-Id',
+  'X-Requested-With',
+]
+
+/** 创建 API Service HTTP 应用。 */
+export function {{api.serviceAppFactoryName}}(_options: CreateApiServiceAppOptions = {}) {
+  const servConfig = core.config.getOrThrow<ServConfig>('serv')
+{{#if features.crypto}}  const transportMode = _options.transport ?? 'config'
+  const transport = transportMode === 'disabled' || servConfig.transport === false
+    ? undefined
+    : {
+        crypto,
+        keyExchangePath: servConfig.transport.keyExchangePath,
+        excludePaths: [...servConfig.transport.excludePaths],
+        maxClients: servConfig.transport.maxClients,
+      }
+{{else}}  const transport = undefined
+{{/if}}
+{{#if features.iam}}
+  const refreshCookie = _options.refreshCookie === 'disabled' ? undefined : {}
+{{/if}}
+
+  const appOptions: Parameters<typeof serv.createApp>[0] = {
+    contract: {{api.contractExportName}},
+    procedures: {{api.serviceProceduresFactoryName}}({
+      app: {
+        info: {
+          name: pkg.name,
+          version: pkg.version,
+          transportEnabled: transport !== undefined,
+        },
+        startedAt,
+      },
+    }),
+    http: servConfig.http,
+{{#if features.iam}}
+    iam,
+{{/if}}
+    middlewares: [
+      {
+        middleware: serv.cors({
+          origin: origin => resolveCorsOrigin(origin) !== null,
+{{#if features.iam}}          credentials: true,
+{{/if}}          allowedHeaders: DEFAULT_CORS_ALLOWED_HEADERS,{{#if features.crypto}}
+          exposedHeaders: [TRANSPORT_PROTOCOL.ENCRYPTED_HEADER, 'X-Request-Id'],{{/if}}
+        }),
+      },
+    ],
+  }
+{{#if features.iam}}
+
+  appOptions.refreshCookie = refreshCookie
+{{/if}}{{#if features.crypto}}
+  if (transport)
+    appOptions.transport = transport
+{{/if}}
+
+  return serv.createApp(appOptions)
+}
+
+function resolveCorsOrigin(origin: string | undefined): string | null {
+  if (!origin)
+    return null
+  if (WEBVIEW_ORIGINS.has(origin))
+    return origin
+  if (LOOPBACK_ORIGIN_RE.test(origin))
+    return origin
+  return null
+}

package/templates/apps/api/apps/{{projectName}}-service/src/index.ts.hbs

@@ -0,0 +1,21 @@
+import process from 'node:process'
+import { core } from '@h-ai/core'
+import { serv } from '@h-ai/serv'
+import { {{api.serviceAppFactoryName}} } from './app.js'
+import { closeApp, initApp } from './lib/server/init.js'
+
+const logger = core.logger.child({ app: '{{api.servicePackageName}}', scope: 'entrypoint' })
+
+async function main(): Promise<void> {
+  await initApp()
+
+  serv.listen({{api.serviceAppFactoryName}}(), {
+    onListening: info => logger.info('API service listening', { address: info.address, port: info.port }),
+    onClose: closeApp,
+  })
+}
+
+main().catch((error: unknown) => {
+  logger.error('API service failed to start', { error })
+  process.exitCode = 1
+})

package/templates/apps/api/apps/{{projectName}}-service/src/lib/server/init.ts.hbs

@@ -0,0 +1,184 @@
+{{#if features.ai}}import type { AIConfigInput } from '@h-ai/ai'
+{{/if}}{{#if features.cache}}import type { CacheConfigInput } from '@h-ai/cache'
+{{/if}}{{#if features.iam}}import type { IamConfigInput } from '@h-ai/iam'
+{{/if}}{{#if features.crypto}}import type { ServConfig } from '@h-ai/serv'
+{{/if}}{{#if features.storage}}import type { StorageConfigInput } from '@h-ai/storage'
+{{/if}}{{#if features.ai}}import { ai, AIConfigSchema } from '@h-ai/ai'
+{{/if}}{{#if features.cache}}import { cache, CacheConfigSchema } from '@h-ai/cache'
+{{/if}}import { core } from '@h-ai/core'
+{{#if features.crypto}}import { crypto } from '@h-ai/crypto'
+{{/if}}{{#if features.iam}}import { iam, IamConfigSchema } from '@h-ai/iam'
+{{/if}}{{#if features.db}}import { reldb, ReldbConfigSchema } from '@h-ai/reldb'
+{{/if}}import { ServConfigSchema } from '@h-ai/serv'
+{{#if features.storage}}import { storage, StorageConfigSchema } from '@h-ai/storage'
+{{/if}}{{#if features.vecdb}}import { vecdb, VecdbConfigSchema } from '@h-ai/vecdb'
+{{/if}}
+
+{{#if features.db}}type DbConfigInput = Parameters<typeof reldb.init>[0]
+{{/if}}{{#if features.vecdb}}type VecdbConfigInput = Parameters<typeof vecdb.init>[0]
+{{/if}}
+
+let initialized = false
+let initPromise: Promise<void> | null = null
+{{#if features.crypto}}let cryptoInitialized = false
+{{/if}}
+
+export async function initApp(): Promise<void> {
+  if (initialized)
+    return
+  if (initPromise)
+    return initPromise
+
+  initPromise = doInit()
+  try {
+    await initPromise
+    initialized = true
+  }
+  finally {
+    initPromise = null
+  }
+}
+
+async function doInit(): Promise<void> {
+  core.init({
+    configDir: './config',
+    logging: { level: 'info' },
+  })
+
+  const servValidation = core.config.validate('serv', ServConfigSchema)
+  if (!servValidation.success) {
+    throw new Error(`Serv config invalid: ${servValidation.error.message}`)
+  }
+{{#if features.crypto}}
+  const servConfig = core.config.getOrThrow<ServConfig>('serv')
+  if (servConfig.transport !== false) {
+    const cryptoResult = await crypto.init()
+    if (!cryptoResult.success) {
+      throw new Error(`Crypto initialization failed: ${cryptoResult.error.message}`)
+    }
+    cryptoInitialized = true
+  }
+{{/if}}{{#if features.db}}
+
+  const dbValidation = core.config.validate('db', ReldbConfigSchema)
+  if (!dbValidation.success) {
+    throw new Error(`DB config invalid: ${dbValidation.error.message}`)
+  }
+{{/if}}{{#if features.cache}}
+
+  const cacheValidation = core.config.validate('cache', CacheConfigSchema)
+  if (!cacheValidation.success) {
+    throw new Error(`Cache config invalid: ${cacheValidation.error.message}`)
+  }
+{{/if}}{{#if features.vecdb}}
+
+  const vecdbValidation = core.config.validate('vecdb', VecdbConfigSchema)
+  if (!vecdbValidation.success) {
+    throw new Error(`VecDB config invalid: ${vecdbValidation.error.message}`)
+  }
+{{/if}}{{#if features.iam}}
+
+  const iamValidation = core.config.validate('iam', IamConfigSchema)
+  if (!iamValidation.success) {
+    throw new Error(`IAM config invalid: ${iamValidation.error.message}`)
+  }
+{{/if}}{{#if features.storage}}
+
+  const storageValidation = core.config.validate('storage', StorageConfigSchema)
+  if (!storageValidation.success) {
+    throw new Error(`Storage config invalid: ${storageValidation.error.message}`)
+  }
+{{/if}}{{#if features.ai}}
+
+  const aiValidation = core.config.validate('ai', AIConfigSchema)
+  if (!aiValidation.success) {
+    throw new Error(`AI config invalid: ${aiValidation.error.message}`)
+  }
+{{/if}}{{#if features.db}}
+
+  const dbConfig = core.config.getOrThrow<DbConfigInput>('db')
+{{/if}}{{#if features.cache}}  const cacheConfig = core.config.getOrThrow<CacheConfigInput>('cache')
+{{/if}}{{#if features.vecdb}}  const vecdbConfig = core.config.getOrThrow<VecdbConfigInput>('vecdb')
+{{/if}}{{#if features.iam}}  const iamConfig = core.config.getOrThrow<IamConfigInput>('iam')
+{{/if}}{{#if features.storage}}  const storageConfig = core.config.getOrThrow<StorageConfigInput>('storage')
+{{/if}}{{#if features.ai}}  const aiConfig = core.config.getOrThrow<AIConfigInput>('ai')
+{{/if}}{{#if features.db}}
+
+  if (dbConfig.type === 'sqlite') {
+    const fs = await import('node:fs')
+    const path = await import('node:path')
+    const dbDir = path.dirname(dbConfig.database)
+    if (!fs.existsSync(dbDir)) {
+      fs.mkdirSync(dbDir, { recursive: true })
+    }
+  }
+
+  const dbResult = await reldb.init(dbConfig)
+  if (!dbResult.success) {
+    throw new Error(`Database initialization failed: ${dbResult.error.message}`)
+  }
+{{/if}}{{#if features.cache}}
+
+  const cacheResult = await cache.init(cacheConfig)
+  if (!cacheResult.success) {
+    throw new Error(`Cache initialization failed: ${cacheResult.error.message}`)
+  }
+{{/if}}{{#if features.vecdb}}
+
+  const vecdbResult = await vecdb.init(vecdbConfig)
+  if (!vecdbResult.success) {
+    throw new Error(`VecDB initialization failed: ${vecdbResult.error.message}`)
+  }
+{{/if}}{{#if features.iam}}
+
+  const iamResult = await iam.init(iamConfig)
+  if (!iamResult.success) {
+    throw new Error(`IAM initialization failed: ${iamResult.error.message}`)
+  }
+{{/if}}{{#if features.storage}}
+
+  const storageResult = await storage.init(storageConfig)
+  if (!storageResult.success) {
+    throw new Error(`Storage initialization failed: ${storageResult.error.message}`)
+  }
+{{/if}}{{#if features.ai}}
+
+  const aiResult = await ai.init(aiConfig)
+  if (!aiResult.success) {
+    throw new Error(`AI initialization failed: ${aiResult.error.message}`)
+  }
+{{/if}}
+
+  core.logger.info('API service initialized')
+}
+
+export async function closeApp(): Promise<void> {
+  if (!initialized && !initPromise)
+    return
+
+  const closers: Array<readonly [string, () => unknown]> = [
+{{#if features.ai}}    ['ai', () => ai.close()],
+{{/if}}{{#if features.storage}}    ['storage', () => storage.close()],
+{{/if}}{{#if features.iam}}    ['iam', () => iam.close()],
+{{/if}}{{#if features.vecdb}}    ['vecdb', () => vecdb.close()],
+{{/if}}{{#if features.cache}}    ['cache', () => cache.close()],
+{{/if}}{{#if features.db}}    ['reldb', () => reldb.close()],
+{{/if}}  ]
+{{#if features.crypto}}  if (cryptoInitialized) {
+    closers.push(['crypto', () => crypto.close()])
+  }
+{{/if}}
+
+  for (const [name, close] of closers) {
+    try {
+      await close()
+    }
+    catch (error) {
+      core.logger.warn(`Module close failed: ${name}`, { error })
+    }
+  }
+
+  initialized = false
+{{#if features.crypto}}  cryptoInitialized = false
+{{/if}}  core.logger.info('API service closed')
+}

package/templates/apps/api/apps/{{projectName}}-service/src/server/procedures/app-procedures.ts.hbs

@@ -0,0 +1,49 @@
+import type { ServContext } from '@h-ai/serv'
+{{#if features.iam}}import type { AppEchoInput, AppEchoOutputData, AppInfoOutputData } from '{{api.contractPackageName}}'
+{{else}}import type { AppEchoOutputData, AppInfoOutputData } from '{{api.contractPackageName}}'
+{{/if}}
+import { ok } from '@h-ai/core'
+import { serv } from '@h-ai/serv'
+import { appContract } from '{{api.contractPackageName}}'
+
+export interface AppProcedureDeps {
+  readonly info: {
+    readonly name: string
+    readonly version: string
+    readonly transportEnabled: boolean
+  }
+  readonly startedAt: number
+}
+
+const p = serv.implement(appContract).$context<ServContext>()
+
+/** 创建应用自有 procedures。 */
+export function createAppProcedures(deps: AppProcedureDeps) {
+  return p.router({
+    info: p.info.handler(() => {
+      const data: AppInfoOutputData = {
+        name: deps.info.name,
+        version: deps.info.version,
+        transportEnabled: deps.info.transportEnabled,
+        uptimeMs: Math.max(0, Date.now() - deps.startedAt),
+      }
+      return ok(data)
+    }),
+    echo: {{#if features.iam}}p.echo.handler(serv.requireAuth<AppEchoInput, AppEchoOutputData>(({ input, context }) => {
+      const data: AppEchoOutputData = {
+        message: input.message,
+        userId: context.session!.userId,
+        requestId: context.requestId,
+        timestamp: new Date().toISOString(),
+      }
+      return Promise.resolve(ok(data))
+    })){{else}}p.echo.handler(({ input, context }) => {
+      const data: AppEchoOutputData = {
+        message: input.message,
+        requestId: context.requestId,
+        timestamp: new Date().toISOString(),
+      }
+      return ok(data)
+    }){{/if}},
+  })
+}

package/templates/apps/api/apps/{{projectName}}-service/src/server/procedures/index.ts.hbs

@@ -0,0 +1,18 @@
+import type { AppProcedureDeps } from './app-procedures.js'
+{{#if features.ai}}import { ai } from '@h-ai/ai'
+{{/if}}{{#if features.iam}}import { iam } from '@h-ai/iam'
+{{/if}}{{#if features.ai}}import { createAiProcedures } from '@h-ai/serv/features/ai'
+{{/if}}{{#if features.iam}}import { createIamProcedures } from '@h-ai/serv/features/iam'
+{{/if}}{{#if features.storage}}import { createStorageProcedures } from '@h-ai/serv/features/storage'
+import { storage } from '@h-ai/storage'
+{{/if}}import { createAppProcedures } from './app-procedures.js'
+
+/** 创建应用级 procedures 聚合。 */
+export function {{api.serviceProceduresFactoryName}}(deps: { app: AppProcedureDeps }) {
+  return {
+{{#if features.iam}}    iam: createIamProcedures({ iam }),
+{{/if}}{{#if features.storage}}    storage: createStorageProcedures({ storage }),
+{{/if}}{{#if features.ai}}    ai: createAiProcedures({ ai }),
+{{/if}}    app: createAppProcedures(deps.app),
+  }
+}