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

package/dist/index.d.ts

@@ -2,7 +2,19 @@ import { z } from 'zod';
 import * as _h_ai_core from '@h-ai/core';
 import { HaiResult, HaiError } from '@h-ai/core';
 
-/** 镜像制品清单，例如 `{ version: 3, appVersion: '1.2.3', buildId: '1.2.3-build1', partial: false, hasWeb: false, images: [...] }`。 */
+/**
+ * 镜像制品清单，例如 `{ version: 3, appVersion: '1.2.3', buildId: '1.2.3-build1', partial: false, hasWeb: false, images: [...] }`。
+ * 清单格式版本为 3；完整产物必须包含 app，声明 hasWeb 时还须包含 web。结构验证不能代替真实归档校验。
+ * @example
+ * ```ts
+ * import { readFile } from 'node:fs/promises'
+ * import { DeploymentArtifactSchema } from '@h-ai/deploy'
+ * const content = await readFile('.hai/build/docker/build-id/manifest.json', 'utf8')
+ * const parsed = DeploymentArtifactSchema.safeParse(JSON.parse(content))
+ * if (!parsed.success) throw new Error('Invalid artifact manifest')
+ * // Schema 只验证结构；文件路径与 SHA-256 核验使用 readDeploymentArtifact。
+ * ```
+ */
 declare const DeploymentArtifactSchema: z.ZodObject<{
     version: z.ZodLiteral<3>;
     appVersion: z.ZodString;
@@ -22,23 +34,50 @@ declare const DeploymentArtifactSchema: z.ZodObject<{
         containerPort: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-/** 构建器与部署器共享的镜像交付结构；参见 DeploymentArtifactSchema 示例。 */
+/**
+ * 构建器与部署器共享的镜像交付结构；参见 DeploymentArtifactSchema 示例。
+ * @example
+ * ```ts
+ * import type { DeploymentArtifact } from '@h-ai/deploy'
+ * import { readDeploymentArtifact } from '@h-ai/deploy'
+ * const directory = '.hai/build/docker/build-id'
+ * const artifact = await readDeploymentArtifact(directory)
+ * const verified: DeploymentArtifact = artifact
+ * const references = verified.images.map(image => image.imageRef)
+ * ```
+ */
 type DeploymentArtifact = z.infer<typeof DeploymentArtifactSchema>;
 /**
  * 流式计算制品校验和，避免将大镜像一次性读入内存。
- * @example `const checksum = await artifactChecksum("/release/app-1.2.3.tar")`
+ * @throws Error - 文件读取失败；返回真实 tar 内容的 SHA-256，不校验清单其它字段。
+ * @param file - 真实镜像归档文件路径。
+ * @returns 文件内容的 SHA-256 十六进制摘要。
+ * @example
+ * ```ts
+ * import { artifactChecksum } from '@h-ai/deploy'
+ * const digest = await artifactChecksum('.hai/build/docker/build-id/app-1.0.0.tar')
+ * ```
  */
 declare function artifactChecksum(file: string): Promise<string>;
 /**
  * 校验完整构建产物；缺失、损坏或非法清单均抛错，由部署边界转换为 HaiResult。
- * @example `const artifact = await readDeploymentArtifact("/release/build-1")`
+ * @throws Error - 清单、路径、镜像 tar 或摘要校验失败；不能用未验证的清单绕过本函数。
+ * @param directory - 包含已准备制品或部署文件的目录；具体见函数用途。
+ * @returns 已经验证的构建制品清单。
+ * @example
+ * ```ts
+ * import { readDeploymentArtifact } from '@h-ai/deploy'
+ * const directory = '.hai/build/docker/build-id'
+ * const artifact = await readDeploymentArtifact(directory)
+ * const images = artifact.images.map(image => ({ name: image.name, imageRef: image.imageRef }))
+ * ```
  */
 declare function readDeploymentArtifact(directory: string): Promise<DeploymentArtifact>;
 
 /**
  * @h-ai/deploy — 部署配置 Schema
  *
- * 本文件定义部署模块的错误码、Zod Schema 和配置类型。
+ * 本文件定义部署模块的 Zod Schema 和配置类型；错误定义位于 deploy-types.ts。
  * @module deploy-config
  */
 
@@ -84,7 +123,17 @@ declare const DockerSshProviderConfigSchema: z.ZodObject<{
         hostPort: z.ZodNumber;
     }, z.core.$strip>;
 }, z.core.$strip>;
-/** 部署平台配置联合类型（后续可扩展更多平台） */
+/**
+ * 部署平台配置联合类型（后续可扩展更多平台）
+ * 按 type 区分 Vercel 与 docker-ssh；仅校验配置形状，不验证远端连通性或云凭据。
+ * @example
+ * ```ts
+ * import { ProviderConfigSchema } from '@h-ai/deploy'
+ * const result = ProviderConfigSchema.safeParse({ type: 'docker-ssh', expose: { hostPort: 8080 } })
+ * if (!result.success) throw new Error('Invalid deployment provider')
+ * const provider = result.data
+ * ```
+ */
 declare const ProviderConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"vercel">;
     token: z.ZodString;
@@ -113,13 +162,45 @@ declare const ProviderConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         hostPort: z.ZodNumber;
     }, z.core.$strip>;
 }, z.core.$strip>], "type">;
-/** SSH 连接配置（parse 后） */
+/**
+ * SSH 连接配置（parse 后）
+ * 这是 Schema 解析后的类型，默认字段已必填；私钥路径可省略以使用 ssh-agent/默认密钥。
+ * @example
+ * ```ts
+ * import type { SshConfig } from '@h-ai/deploy'
+ * const config: SshConfig = { host: 'deploy.example.net', username: 'deploy', port: 22, strictHostKeyChecking: true, connectTimeoutSeconds: 10 }
+ * ```
+ */
 type SshConfig = z.infer<typeof SshConfigSchema>;
-/** 端口暴露配置（parse 后） */
+/**
+ * 端口暴露配置（parse 后）
+ * @example
+ * ```ts
+ * import type { PortExposeConfig } from '@h-ai/deploy'
+ * const ports: PortExposeConfig = { type: 'port', hostPort: 8080, containerPort: 3000 }
+ * ```
+ */
 type PortExposeConfig = z.infer<typeof PortExposeSchema>;
-/** docker-ssh 部署平台配置（parse 后） */
+/**
+ * docker-ssh 部署平台配置（parse 后）
+ * SSH 可省略用于离线打包；真正在线发布必须提供 SSH 配置。
+ * @example
+ * ```ts
+ * import type { DockerSshProviderConfig } from '@h-ai/deploy'
+ * const provider: DockerSshProviderConfig = { type: 'docker-ssh', remote: { baseDir: '/opt/hai/apps', runtime: 'auto' }, expose: { type: 'port', hostPort: 8080, containerPort: 3000 } }
+ * ```
+ */
 type DockerSshProviderConfig = z.infer<typeof DockerSshProviderConfigSchema>;
-/** 部署模块完整配置 Schema */
+/**
+ * 部署模块完整配置 Schema
+ * @example
+ * ```ts
+ * import { DeployConfigSchema } from '@h-ai/deploy'
+ * const parsed = DeployConfigSchema.safeParse({ environment: 'prod', provider: { type: 'docker-ssh', expose: { hostPort: 8080 } } })
+ * if (!parsed.success) throw new Error('Invalid deployment configuration')
+ * const baseDir = parsed.data.provider.type === 'docker-ssh' ? parsed.data.provider.remote.baseDir : undefined
+ * ```
+ */
 declare const DeployConfigSchema: z.ZodObject<{
     environment: z.ZodOptional<z.ZodString>;
     provider: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -186,14 +267,36 @@ declare const DeployConfigSchema: z.ZodObject<{
         }>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-/** 部署配置类型（parse 后） */
+/**
+ * 部署配置类型（parse 后）
+ * @example
+ * ```ts
+ * import type { DeployConfig } from '@h-ai/deploy'
+ * const config: DeployConfig = { environment: 'prod', provider: { type: 'docker-ssh', remote: { baseDir: '/opt/hai/apps', runtime: 'auto' }, expose: { type: 'port', hostPort: 8080, containerPort: 3000 } } }
+ * ```
+ */
 type DeployConfig = z.infer<typeof DeployConfigSchema>;
-/** 部署配置输入类型（用户输入） */
+/**
+ * 部署配置输入类型（用户输入）
+ * @example
+ * ```ts
+ * import type { DeployConfigInput } from '@h-ai/deploy'
+ * const input: DeployConfigInput = { provider: { type: 'docker-ssh', expose: { hostPort: 8080 } } } // 由 init 应用 remote 等默认值。
+ * ```
+ */
 type DeployConfigInput = z.input<typeof DeployConfigSchema>;
 
 /** 部署环境的加载和持久化；公开环境文件不保存真实凭据。 */
 
-/** 部署环境快照；例如 prod 的 targetValues 只来自 `.env.prod`，不包含基础/私有覆盖。 */
+/**
+ * 部署环境快照；例如 prod 的 targetValues 只来自 `.env.prod`，不包含基础/私有覆盖。
+ * @example
+ * ```ts
+ * import type { DeploymentEnvironment } from '@h-ai/deploy'
+ * const environment: DeploymentEnvironment = { environment: 'prod', envDir: '/workspace/shop', values: { HAI_DB_TYPE: 'postgresql' }, targetValues: { HAI_DB_TYPE: 'postgresql' } }
+ * // values 可能还含私有凭据，不能整体写入日志。
+ * ```
+ */
 interface DeploymentEnvironment {
     /** 文件模式（dev/test/prod 或其他合法模式名）。 */
     environment: string;
@@ -211,17 +314,32 @@ interface DeploymentEnvironment {
  * @param path - YAML 文件绝对路径
  * @param values - 已加载的目标环境变量
  * @returns 配置对象；解析错误已脱敏
- * @example `loadDeploymentConfig('deploy', '/app/config/_deploy.yml', environment.values)`
+ * @example
+ * ```ts
+ * import { loadDeploymentConfig, loadDeploymentEnvironment } from '@h-ai/deploy'
+ * const environment = loadDeploymentEnvironment({ environment: 'prod', envDir: process.cwd() })
+ * if (!environment.success) throw new Error(environment.error.message)
+ * const config = loadDeploymentConfig('deploy', `${process.cwd()}/config/_deploy.yml`, environment.data.values)
+ * if (!config.success) throw new Error(config.error.message)
+ * // 返回对象仍需经 DeployConfigSchema 或 deploy.init 验证。
+ * ```
  */
 declare function loadDeploymentConfig(name: string, path: string, values: Record<string, string | undefined>): HaiResult<Record<string, unknown>>;
 /**
  * 加载部署环境；指定环境文件缺失时返回错误并要求用户创建。
+ * 进程环境优先于 .env.local、目标环境文件、基础文件；targetValues 只记录目标文件显式项，不包含其它覆盖。
  * @param options - 模式、环境目录与是否强制存在目标文件
  * @param options.environment - dev/test/prod 或自定义模式
  * @param options.envDir - 环境文件所在目录
  * @param options.requireFile - 默认 true；扫描无显式环境时可只读取已有基础文件
  * @returns 环境快照，可能包含私有值，不得直接输出
- * @example `loadDeploymentEnvironment({ environment: 'prod', envDir: '.' })`
+ * @example
+ * ```ts
+ * import { loadDeploymentEnvironment } from '@h-ai/deploy'
+ * const loaded = loadDeploymentEnvironment({ environment: 'prod', envDir: process.cwd() })
+ * if (!loaded.success) throw new Error(loaded.error.message)
+ * const explicitlyConfigured = loaded.data.targetValues.HAI_DB_TYPE
+ * ```
  */
 declare function loadDeploymentEnvironment(options: {
     environment: string;
@@ -236,13 +354,32 @@ declare function loadDeploymentEnvironment(options: {
  * @param options - private 为 true 时所有值只保存在本机；适用于 SSH 地址、端口及密钥路径
  * @param options.private - 是否将全部值仅保存到 .env.local
  * @returns 已保存的变量名或脱敏错误
- * @example `saveDeploymentEnvironment(snapshot, { HAI_DB_TYPE: 'postgresql' })`
- * @example `saveDeploymentEnvironment(snapshot, { HAI_DEPLOY_PROVIDER: JSON.stringify(provider) }, { private: true })`
+ * @example
+ * ```ts
+ * import { loadDeploymentEnvironment, saveDeploymentEnvironment } from '@h-ai/deploy'
+ * const loaded = loadDeploymentEnvironment({ environment: 'prod', envDir: process.cwd() })
+ * if (!loaded.success) throw new Error(loaded.error.message)
+ * const saved = saveDeploymentEnvironment(loaded.data, { HAI_DB_HOST: 'db' })
+ * if (!saved.success) throw new Error(saved.error.message)
+ * // 密钥应以 { private: true } 写入被忽略的 .env.local，不能放公共环境文件。
+ * ```
  */
 declare function saveDeploymentEnvironment(environment: DeploymentEnvironment, values: Record<string, string>, options?: {
     private?: boolean;
 }): HaiResult<string[]>;
 
+/**
+ *
+ * @example
+ * ```ts
+ * import { err } from '@h-ai/core'
+ * import { HaiDeployError } from '@h-ai/deploy'
+ * const result = err(HaiDeployError.CONFIG_ERROR, 'Invalid deployment configuration')
+ * if (!result.success && result.error.code === HaiDeployError.CONFIG_ERROR.code) {
+ *   process.stderr.write(result.error.message + '\n')
+ * }
+ * ```
+ */
 declare const HaiDeployError: {
     readonly DEPLOY_FAILED: _h_ai_core.HaiErrorDef;
     readonly PROJECT_CREATE_FAILED: _h_ai_core.HaiErrorDef;
@@ -265,15 +402,12 @@ declare const HaiDeployError: {
 /**
  * 部署错误接口
  *
- * 所有部署操作返回的错误都遵循此接口。
- *
+ * 用于组合错误定义、消息与可选 cause 的描述对象；业务操作返回的 error 遵循 core.HaiError，请按 success 分支读取 code/message。
  * @example
  * ```ts
- * const result = await deploy.deployApp('./apps/my-app')
- * if (!result.success) {
- *   const error: DeployError = result.error
- *   // 根据 error.code 处理
- * }
+ * import type { DeployError } from '@h-ai/deploy'
+ * import { HaiDeployError } from '@h-ai/deploy'
+ * const detail: DeployError = { def: HaiDeployError.DEPLOY_FAILED, message: 'Deployment failed' }
  * ```
  */
 interface DeployError {
@@ -284,18 +418,47 @@ interface DeployError {
     /** 原始错误（可选） */
     cause?: unknown;
 }
-/** 基础设施服务类型 */
+/**
+ * 基础设施服务类型
+ * @example
+ * ```ts
+ * import type { ServiceType } from '@h-ai/deploy'
+ * const service: ServiceType = 'db'
+ * ```
+ */
 type ServiceType = 'db' | 'cache' | 'storage' | 'email' | 'sms' | 'vecdb' | 'ldap';
-/** 每项中间件的处理方式；keep 不修改配置，也不开通服务。 */
+/**
+ * 每项中间件的处理方式；keep 不修改配置，也不开通服务。
+ * @example
+ * ```ts
+ * import type { MiddlewareMode } from '@h-ai/deploy'
+ * const mode: MiddlewareMode = 'keep' // 复用已有服务，不修改连接配置或自动开通。
+ * ```
+ */
 type MiddlewareMode = 'default' | 'custom' | 'keep';
-/** 扫描环境；例如 `{ environment: 'test', envDir: '/workspace/app' }`。 */
+/**
+ * 扫描环境；例如 `{ environment: 'test', envDir: '/workspace/app' }`。
+ * @example
+ * ```ts
+ * import type { DeployScanOptions } from '@h-ai/deploy'
+ * const options: DeployScanOptions = { environment: 'prod', envDir: '/workspace/shop' }
+ * ```
+ */
 interface DeployScanOptions {
     /** 环境文件模式。 */
     environment?: string;
     /** 环境文件目录；默认自动定位到应用或 workspace 根。 */
     envDir?: string;
 }
-/** 依赖对应的中间件；例如 IAM 的 LDAP 位于 `iam.ldap`，可处于 disabled 状态。 */
+/**
+ * 依赖对应的中间件；例如 IAM 的 LDAP 位于 `iam.ldap`，可处于 disabled 状态。
+ * @example
+ * ```ts
+ * import type { MiddlewareRequirement } from '@h-ai/deploy'
+ * const requirement: MiddlewareRequirement = { service: 'db', backend: 'postgresql', source: '@h-ai/reldb', configName: 'db', configPath: [], envPrefix: 'HAI_DB', config: { host: 'db', database: 'shop' } }
+ * // config 可能含私有值；展示时只选择安全字段。
+ * ```
+ */
 interface MiddlewareRequirement {
     /** 中间件类别。 */
     service: ServiceType;
@@ -316,6 +479,16 @@ interface MiddlewareRequirement {
  * 应用扫描结果
  *
  * 由 scanner 分析应用目录后返回，描述应用的框架类型、依赖和部署需求。
+ * 扫描是文件系统能力，不依赖 init，也不代表远程服务已经连通。
+ * @example
+ * ```ts
+ * import type { ScanResult } from '@h-ai/deploy'
+ * import { deploy } from '@h-ai/deploy'
+ * const result = await deploy.scan(process.cwd(), { environment: 'prod' })
+ * if (!result.success) throw new Error(result.error.message)
+ * const scan: ScanResult = result.data
+ * const services = scan.requiredServices
+ * ```
  */
 interface ScanResult {
     /** 调用者指定的部署目录，对应 lockfile 中的一个 importer。 */
@@ -343,6 +516,12 @@ interface ScanResult {
  * 部署结果
  *
  * 包含部署后的访问 URL、状态和已设置的环境变量。
+ * @example
+ * ```ts
+ * import type { DeployResult } from '@h-ai/deploy'
+ * const packaged: DeployResult = { url: '', deploymentId: 'deploy-shop-001', status: 'packaged', bundlePath: '/workspace/shop/.hai/deploy/shop-1.0.0.tar', envVarsSet: [], provider: 'docker-ssh', healthCheck: 'skipped' }
+ * // packaged 只代表交付包生成；不将其展示为服务已上线。
+ * ```
  */
 interface DeployResult {
     /** 部署后的访问 URL */
@@ -366,6 +545,12 @@ interface DeployResult {
  * 基础设施开通结果
  *
  * 由 Provisioner 开通服务后返回，包含要注入到部署平台的环境变量。
+ * @example
+ * ```ts
+ * import type { ProvisionResult } from '@h-ai/deploy'
+ * const reused: ProvisionResult = { resourceStatus: 'reused', serviceType: 'db', provisionerName: 'neon', envVars: { HAI_DB_TYPE: 'postgresql' }, resourceInfo: 'Existing shop database' }
+ * // envVars 可能含密码；不能直接输出。
+ * ```
  */
 interface ProvisionResult {
     /** 本次新建或复用；凭证型服务始终为 reused */
@@ -379,7 +564,15 @@ interface ProvisionResult {
     /** 资源标识信息（如项目名、数据库名等），用于日志和展示 */
     resourceInfo: string;
 }
-/** 部署失败后的安全恢复信息，不含环境变量值或原始异常。 */
+/**
+ * 部署失败后的安全恢复信息，不含环境变量值或原始异常。
+ * @example
+ * ```ts
+ * import type { DeployRecoveryInfo } from '@h-ai/deploy'
+ * const recovery: DeployRecoveryInfo = { projectName: 'shop', stage: 'provision', resources: [{ serviceType: 'db', provisionerName: 'neon', resourceInfo: 'shop', resourceStatus: 'unknown' }] }
+ * // 先在供应商控制台核对 unknown 资源；避免重复创建计费资源。
+ * ```
+ */
 interface DeployRecoveryInfo {
     projectName: string;
     stage: string;
@@ -391,7 +584,40 @@ interface DeployRecoveryInfo {
         resourceStatus: 'created' | 'reused' | 'unknown';
     }>;
 }
-/** 部署选项 */
+/**
+ * 命令失败后的已核验执行状态；远端 finished 仅指部署脚本及恢复已完成，不代表容器停止。
+ * @example
+ * ```ts
+ * import type { DeployCommandState } from '@h-ai/deploy'
+ * const state: DeployCommandState = { reason: 'timeout', localTermination: 'confirmed', remoteExecution: 'unknown', deploymentId: 'deploy-shop-001', resultFile: '/opt/hai/apps/shop/results/deploy-shop-001' }
+ * if (state.remoteExecution === 'unknown') process.stderr.write('Verify the matching remote deployment result before retrying\n')
+ * ```
+ */
+interface DeployCommandState {
+    /** 失败触发原因。 */
+    reason: 'timeout' | 'output' | 'input' | 'spawn' | 'exit' | 'configuration';
+    /** 本地受管理树已全部退出、无法证明，或尚未启动。 */
+    localTermination: 'confirmed' | 'unknown' | 'not-started';
+    /** SSH 失败默认 unknown；读取匹配部署 ID 的完整终态结果后才为 finished。 */
+    remoteExecution?: 'unknown' | 'finished';
+    /** 本次不可变部署 ID，可与服务器结果核对。 */
+    deploymentId?: string;
+    /** 服务器端结果文件；无凭据。 */
+    resultFile?: string;
+    /** 匹配终态结果中的真实脚本退出码。 */
+    remoteExitCode?: number;
+    /** 匹配终态结果中的最后阶段。 */
+    remoteStage?: string;
+}
+/**
+ * 部署选项
+ * 仅更新指定服务时仍受完整/部分制品与首次部署约束；bundleOnly 不触发 SSH。
+ * @example
+ * ```ts
+ * import type { DeployAppOptions } from '@h-ai/deploy'
+ * const options: DeployAppOptions = { environment: 'prod', bundleOnly: true, artifactDir: '.hai/build/docker/build-id', selectedServices: ['app'], output: '.hai/deploy/shop.tar' }
+ * ```
+ */
 interface DeployAppOptions {
     /** 接收实际执行阶段，用于终端进度显示；不包含凭据或配置原文。 */
     onProgress?: (stage: 'packaging' | 'preflight' | 'images' | 'dependencies' | 'start' | 'health' | 'complete') => void;
@@ -420,15 +646,58 @@ interface DeployAppOptions {
  * Deploy 凭证文件操作。
  *
  * 这些方法仅操作 `~/.hai/credentials.yml`，不依赖 `deploy.init()`。
+ * @example
+ * ```ts
+ * import type { DeployCredentialOperations } from '@h-ai/deploy'
+ * import { deploy } from '@h-ai/deploy'
+ * const credentials: DeployCredentialOperations = deploy.credentials
+ * const path = credentials.getPath() // 无需先 init。
+ * ```
  */
 interface DeployCredentialOperations {
-    /** 获取凭证文件绝对路径。 */
+    /**
+     * 获取凭证文件绝对路径。
+     * @example
+     * ```ts
+     * import { deploy } from '@h-ai/deploy'
+     * const path = deploy.credentials.getPath() // 当前用户的全局凭证文件。
+     * ```
+     */
     getPath: () => string;
-    /** 加载凭证文件并注入 `process.env`。 */
+    /**
+     * 加载凭证文件并注入 `process.env`。
+     * @example
+     * ```ts
+     * import { deploy } from '@h-ai/deploy'
+     * const loaded = deploy.credentials.load()
+     * if (!loaded.success) throw new Error(loaded.error.message)
+     * const names = loaded.data // 不输出被注入的值。
+     * ```
+     */
     load: () => HaiResult<string[]>;
-    /** 保存单个凭证。 */
+    /**
+     * 保存单个凭证。
+     * @example
+     * ```ts
+     * import { deploy } from '@h-ai/deploy'
+     * const token = process.env.HAI_DEPLOY_PROVIDER_TOKEN
+     * if (!token) throw new Error('Provide HAI_DEPLOY_PROVIDER_TOKEN privately')
+     * const saved = deploy.credentials.save('HAI_DEPLOY_PROVIDER_TOKEN', token)
+     * if (!saved.success) throw new Error(saved.error.message)
+     * ```
+     */
     save: (key: string, value: string) => HaiResult<void>;
-    /** 批量保存凭证。 */
+    /**
+     * 批量保存凭证。
+     * @example
+     * ```ts
+     * import { deploy } from '@h-ai/deploy'
+     * const token = process.env.HAI_DEPLOY_PROVIDER_TOKEN
+     * if (!token) throw new Error('Provide HAI_DEPLOY_PROVIDER_TOKEN privately')
+     * const saved = deploy.credentials.saveAll({ HAI_DEPLOY_PROVIDER_TOKEN: token })
+     * if (!saved.success) throw new Error(saved.error.message)
+     * ```
+     */
     saveAll: (entries: Record<string, string>) => HaiResult<void>;
 }
 /**
@@ -441,25 +710,51 @@ interface DeployCredentialOperations {
  * - `deploy.provisionAll()` — 开通所有已配置的基础设施
  * - `deploy.deployApp()` — 完整部署流程
  * - `deploy.close()` — 关闭模块
- *
+ * scan 与 credentials 不需要 init；部署与开通遵循 init → 检查结果 → use → finally close。close 返回 Promise<void>，不伪造 HaiResult。
  * @example
  * ```ts
+ * import type { DeployFunctions } from '@h-ai/deploy'
  * import { deploy } from '@h-ai/deploy'
- *
- * await deploy.init({ provider: { type: 'vercel', token: 'xxx' } })
- * const result = await deploy.deployApp('./apps/my-app')
- * if (result.success) {
- *   console.log(`Deployed: ${result.data.url}`)
- * }
- * await deploy.close()
+ * const operations: DeployFunctions = deploy
+ * const scan = await operations.scan(process.cwd())
+ * if (!scan.success) throw new Error(scan.error.message)
+ * const required = scan.data.requiredServices
  * ```
  */
 interface DeployFunctions {
     /** 全局部署凭证文件操作。 */
     readonly credentials: DeployCredentialOperations;
-    /** 初始化模块（加载配置、创建 Provider 和 Provisioner 实例） */
+    /**
+     * 初始化模块（加载配置、创建 Provider 和 Provisioner 实例）
+     * @example
+     * ```ts
+     * import { deploy } from '@h-ai/deploy'
+     * const initialized = await deploy.init({ provider: { type: 'docker-ssh', expose: { hostPort: 8080 } } })
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const ready = deploy.isInitialized
+     * }
+     * finally {
+     *   await deploy.close()
+     * }
+     * ```
+     */
     init: (config: DeployConfigInput) => Promise<HaiResult<void>>;
-    /** 关闭模块 */
+    /**
+     * 关闭模块
+     * @example
+     * ```ts
+     * import { deploy } from '@h-ai/deploy'
+     * const initialized = await deploy.init({ provider: { type: 'docker-ssh', expose: { hostPort: 8080 } } })
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const provider = deploy.config?.provider.type
+     * }
+     * finally {
+     *   await deploy.close() // Promise<void>；不检查不存在的 success 字段。
+     * }
+     * ```
+     */
     close: () => Promise<void>;
     /** 当前配置 */
     readonly config: DeployConfig | null;
@@ -471,6 +766,13 @@ interface DeployFunctions {
      * 这是纯文件系统分析能力，不依赖云端认证状态，可在 `deploy.init()` 之前调用。
      *
      * @param appDir - 应用根目录路径
+     * @example
+     * ```ts
+     * import { deploy } from '@h-ai/deploy'
+     * const scanned = await deploy.scan(process.cwd(), { environment: 'prod' })
+     * if (!scanned.success) throw new Error(scanned.error.message)
+     * const services = scanned.data.requiredServices // 无需 init。
+     * ```
      */
     scan: (appDir: string, options?: DeployScanOptions) => Promise<HaiResult<ScanResult>>;
     /**
@@ -478,6 +780,28 @@ interface DeployFunctions {
      *
      * @param projectName - 用于资源命名的项目名
      * @returns 所有 Provisioner 的结果列表
+     * @example
+     * ```ts
+     * import { deploy, getDeployRecovery } from '@h-ai/deploy'
+     * const apiKey = process.env.HAI_DEPLOY_SERVICES_DB_APIKEY
+     * if (!apiKey) throw new Error('Provide HAI_DEPLOY_SERVICES_DB_APIKEY privately')
+     * const initialized = await deploy.init({ provider: { type: 'docker-ssh', expose: { hostPort: 8080 } }, services: { db: { provisioner: 'neon', apiKey } } })
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   // 会访问真实云服务并可能新建资源。
+     *   const result = await deploy.provisionAll('shop', ['db'])
+     *   if (!result.success) {
+     *     const recovery = getDeployRecovery(result.error)
+     *     if (recovery?.resources.some(resource => resource.resourceStatus === 'unknown')) {
+     *       process.stderr.write('Verify unknown resources at the provider before retrying\n')
+     *     }
+     *     throw new Error(result.error.message)
+     *   }
+     * }
+     * finally {
+     *   await deploy.close()
+     * }
+     * ```
      */
     provisionAll: (projectName: string, services?: ServiceType[]) => Promise<HaiResult<ProvisionResult[]>>;
     /**
@@ -485,6 +809,21 @@ interface DeployFunctions {
      *
      * @param appDir - 应用根目录路径
      * @param options - 部署选项
+     * @example
+     * ```ts
+     * import { deploy } from '@h-ai/deploy'
+     * const initialized = await deploy.init({ provider: { type: 'docker-ssh', expose: { hostPort: 8080 } } })
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   // 当前项目必须已有构建镜像清单与生产环境配置。
+     *   const result = await deploy.deployApp(process.cwd(), { environment: 'prod', bundleOnly: true })
+     *   if (!result.success) throw new Error(result.error.message)
+     *   const status = result.data.status // packaged 不代表线上运行。
+     * }
+     * finally {
+     *   await deploy.close()
+     * }
+     * ```
      */
     deployApp: (appDir: string, options?: DeployAppOptions) => Promise<HaiResult<DeployResult>>;
 }
@@ -498,14 +837,29 @@ interface DeployFunctions {
 
 /**
  * Deploy 模块单例
- *
+ * 每次 init 检查 HaiResult；只打包不会连接 SSH，成功打包也不代表服务器已部署。远端 unknown 必须先核对匹配部署 ID 的结果，不能盲目重试。
  * @example
  * ```ts
- * import { deploy } from '@h-ai/deploy'
- *
- * await deploy.init({ provider: { type: 'vercel', token: 'xxx' } })
- * const result = await deploy.deployApp('./apps/my-app')
- * await deploy.close()
+ * import { deploy, getDeployCommandState } from '@h-ai/deploy'
+ * const initialized = await deploy.init({ provider: { type: 'docker-ssh', expose: { hostPort: 8080 } } })
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   // 当前项目已有镜像产物与部署环境；只打包，不连接服务器。
+ *   const result = await deploy.deployApp(process.cwd(), { environment: 'prod', bundleOnly: true })
+ *   if (!result.success) {
+ *     const state = getDeployCommandState(result.error)
+ *     if (state?.remoteExecution === 'unknown') {
+ *       process.stderr.write('Inspect the matching server result before retrying\n')
+ *     }
+ *     throw new Error(result.error.message)
+ *   }
+ *   if (result.data.status === 'packaged') {
+ *     const bundle = result.data.bundlePath
+ *   }
+ * }
+ * finally {
+ *   await deploy.close()
+ * }
  * ```
  */
 declare const deploy: DeployFunctions;
@@ -518,17 +872,16 @@ declare const deploy: DeployFunctions;
  */
 /**
  * 获取部署模块文案
- *
+ * 使用 core 请求/全局 locale 的现有中英字典；不自行缓存调用时的语言。
  * @param key - 文案 Key
  * @param options - 插值参数与格式化选项
  * @returns 本地化后的文案字符串
- *
- * @example
+ * @example 模块内部上下文
  * ```ts
- * const text = deployM('deploy_notInitialized')
+ * const message = deployM('deploy_sshRequired')
  * ```
  */
-declare const deployM: (key: "deploy_notInitialized" | "deploy_initFailed" | "deploy_unsupportedProviderType" | "deploy_unsupportedProvisionerType" | "deploy_configTokenRequired" | "deploy_authRequired" | "deploy_authFailed" | "deploy_projectCreateFailed" | "deploy_uploadFailed" | "deploy_deployFailed" | "deploy_provisionFailed" | "deploy_adapterMissing" | "deploy_scanFailed" | "deploy_envVarFailed" | "deploy_credentialError" | "deploy_credentialInvalidKey" | "deploy_credentialSaved" | "deploy_credentialLoaded" | "deploy_configError" | "deploy_credentialMissing" | "deploy_apiError" | "deploy_fileUploadFailed" | "deploy_provisionNoResult" | "deploy_recoveryFailure" | "deploy_recoverySuggestion" | "deploy_commandTimeout" | "deploy_commandFailed" | "deploy_remoteConnectFailed" | "deploy_remoteRuntimeMissing" | "deploy_imageTransferFailed" | "deploy_healthCheckFailed" | "deploy_invalidEnvironment" | "deploy_environmentMissing" | "deploy_environmentReadFailed" | "deploy_environmentWriteFailed" | "deploy_multipleApplications" | "deploy_purposeSqlite" | "deploy_purposeDatabase" | "deploy_purposeMemory" | "deploy_purposeLocal" | "deploy_purposeCache" | "deploy_purposeStorage" | "deploy_purposeVector" | "deploy_purposeDisabled" | "deploy_purposeLdap" | "deploy_purposeConsole" | "deploy_purposeEmail" | "deploy_purposeSms" | "deploy_webProxyInvalid" | "deploy_artifactInvalid" | "deploy_sshRequired" | "deploy_bundleInstructions" | "deploy_bundleMetadata" | "deploy_bundleOnlyContainer" | "deploy_selectedContainerOnly" | "deploy_selectionInvalid" | "deploy_storageArtifactRequired" | "deploy_imageVersionRequired" | "deploy_bundleRuntimeRequired" | "deploy_bundleFailed" | "deploy_configFileInvalid" | "deploy_configFileUnreadable" | "deploy_bundleNameInvalid" | "deploy_secretsInvalid", options?: _h_ai_core.MessageOptions) => string;
+declare const deployM: (key: "deploy_notInitialized" | "deploy_initFailed" | "deploy_unsupportedProviderType" | "deploy_unsupportedProvisionerType" | "deploy_configTokenRequired" | "deploy_authRequired" | "deploy_authFailed" | "deploy_projectCreateFailed" | "deploy_uploadFailed" | "deploy_deployFailed" | "deploy_provisionFailed" | "deploy_adapterMissing" | "deploy_scanFailed" | "deploy_envVarFailed" | "deploy_credentialError" | "deploy_credentialInvalidKey" | "deploy_credentialSaved" | "deploy_credentialLoaded" | "deploy_configError" | "deploy_credentialMissing" | "deploy_apiError" | "deploy_fileUploadFailed" | "deploy_provisionNoResult" | "deploy_recoveryFailure" | "deploy_recoverySuggestion" | "deploy_commandTimeout" | "deploy_commandFailed" | "deploy_remoteConnectFailed" | "deploy_remoteRuntimeMissing" | "deploy_imageTransferFailed" | "deploy_healthCheckFailed" | "deploy_invalidEnvironment" | "deploy_environmentMissing" | "deploy_environmentReadFailed" | "deploy_environmentWriteFailed" | "deploy_multipleApplications" | "deploy_purposeSqlite" | "deploy_purposeDatabase" | "deploy_purposeMemory" | "deploy_purposeLocal" | "deploy_purposeCache" | "deploy_purposeStorage" | "deploy_purposeVector" | "deploy_purposeDisabled" | "deploy_purposeLdap" | "deploy_purposeConsole" | "deploy_purposeEmail" | "deploy_purposeSms" | "deploy_webProxyInvalid" | "deploy_artifactInvalid" | "deploy_sshRequired" | "deploy_bundleInstructions" | "deploy_bundleMetadata" | "deploy_targetHost" | "deploy_targetPort" | "deploy_targetUsername" | "deploy_targetIdentityFile" | "deploy_targetKnownHostsFile" | "deploy_targetStrictHostKeyChecking" | "deploy_targetConnectTimeoutSeconds" | "deploy_targetDirectory" | "deploy_targetBundle" | "deploy_bundleOnlyContainer" | "deploy_selectedContainerOnly" | "deploy_selectionInvalid" | "deploy_storageArtifactRequired" | "deploy_imageVersionRequired" | "deploy_bundleRuntimeRequired" | "deploy_bundleFailed" | "deploy_configFileInvalid" | "deploy_configFileUnreadable" | "deploy_bundleNameInvalid" | "deploy_secretsInvalid" | "deploy_localStopped" | "deploy_localUnknown" | "deploy_localNotStarted" | "deploy_commandOutputFailed" | "deploy_commandInputFailed" | "deploy_commandTreeActive" | "deploy_commandExecutionFailed" | "deploy_remoteUnknown" | "deploy_remoteFinished", options?: _h_ai_core.MessageOptions) => string;
 
 /**
  * 部署中间件的后端与连接字段目录，供扫描、CLI 和容器规划共同使用。
@@ -536,7 +889,14 @@ declare const deployM: (key: "deploy_notInitialized" | "deploy_initFailed" | "de
  * @module deploy-middleware
  */
 
-/** 连接字段；例如 `{ name: 'port', defaultValue: '5432', kind: 'port' }`。 */
+/**
+ * 连接字段；例如 `{ name: 'port', defaultValue: '5432', kind: 'port' }`。
+ * @example
+ * ```ts
+ * import type { MiddlewareField } from '@h-ai/deploy'
+ * const field: MiddlewareField = { name: 'port', defaultValue: '5432', required: true, kind: 'port' }
+ * ```
+ */
 interface MiddlewareField {
     /** 模块配置字段名，camelCase 不拆词。 */
     name: string;
@@ -553,7 +913,14 @@ interface MiddlewareField {
     /** 数值上限；例如 Redis db 为 15。 */
     maximum?: number;
 }
-/** 后端目录项；例如 PostgreSQL 对应 `backend: 'postgresql'`。 */
+/**
+ * 后端目录项；例如 PostgreSQL 对应 `backend: 'postgresql'`。
+ * @example
+ * ```ts
+ * import type { MiddlewareBackend } from '@h-ai/deploy'
+ * const backend: MiddlewareBackend = { backend: 'postgresql', label: 'PostgreSQL', purpose: 'deploy_purposeDatabase', fields: [{ name: 'database', required: true }] }
+ * ```
+ */
 interface MiddlewareBackend {
     /** 模块 Schema 接受的后端标识。 */
     backend: string;
@@ -569,16 +936,54 @@ interface MiddlewareBackend {
 /**
  * 所有可部署中间件的连接目录。
  * SQLite、memory、local 与 disabled 保留本地/禁用语义，不创建无关 sidecar。
- * @example `DEPLOY_MIDDLEWARE.db.map(item => item.label)` 返回数据库选择项。
+ * 目录同时描述本机、禁用、自建与云后端；存在依赖不等于必须开通新资源。
+ * @example
+ * ```ts
+ * import { DEPLOY_MIDDLEWARE, describeMiddlewareBackend } from '@h-ai/deploy'
+ * const choices = DEPLOY_MIDDLEWARE.db.map(backend => ({ value: backend.backend, description: describeMiddlewareBackend(backend) }))
+ * ```
  */
 declare const DEPLOY_MIDDLEWARE: Record<ServiceType, MiddlewareBackend[]>;
 /**
  * 返回当前语言的后端用途说明。
- * @example `describeMiddlewareBackend(DEPLOY_MIDDLEWARE.db[0])`
+ * @param backend - 部署目录中的后端条目。
+ * @returns 当前 locale 的用途说明。
+ * @example
+ * ```ts
+ * import { DEPLOY_MIDDLEWARE, describeMiddlewareBackend } from '@h-ai/deploy'
+ * const backend = DEPLOY_MIDDLEWARE.db.find(item => item.backend === 'postgresql')
+ * if (backend) {
+ *   const description = describeMiddlewareBackend(backend)
+ * }
+ * ```
  */
 declare function describeMiddlewareBackend(backend: MiddlewareBackend): string;
 
-/** 读取错误中的恢复清单；仅返回明确允许展示的字段。 */
+/**
+ * 读取命令失败的安全状态；不把本地 SSH 退出解释为远端停止。
+ * @param error - 部署错误
+ * @returns 通过结构校验的命令状态，或 undefined
+ * @example
+ * ```ts
+ * import { getDeployCommandState, HaiDeployError } from '@h-ai/deploy'
+ * const state = getDeployCommandState({ ...HaiDeployError.REMOTE_COMMAND_FAILED, message: 'SSH connection interrupted', ext: { commandExecution: { reason: 'exit', localTermination: 'confirmed', remoteExecution: 'unknown' } } })
+ * if (state?.remoteExecution === 'unknown') process.stderr.write('Remote execution is unknown\n')
+ * ```
+ */
+declare function getDeployCommandState(error: HaiError): DeployCommandState | undefined;
+/**
+ * 读取错误中的恢复清单；仅返回明确允许展示的字段。
+ * @param error - 上层捕获的部署 HaiError；不直接展示其 cause。
+ * @returns 安全恢复清单；结构不满足约定时为 undefined。
+ * @example
+ * ```ts
+ * import { getDeployRecovery, HaiDeployError } from '@h-ai/deploy'
+ * const recovery = getDeployRecovery({ ...HaiDeployError.PROVISION_FAILED, message: 'Provisioning failed', ext: { recovery: { projectName: 'shop', stage: 'provision', resources: [] } } })
+ * if (recovery) {
+ *   const stage = recovery.stage
+ * }
+ * ```
+ */
 declare function getDeployRecovery(error: HaiError): DeployRecoveryInfo | undefined;
 
-export { DEPLOY_MIDDLEWARE, type DeployAppOptions, type DeployConfig, type DeployConfigInput, DeployConfigSchema, type DeployCredentialOperations, type DeployError, type DeployFunctions, type DeployRecoveryInfo, type DeployResult, type DeployScanOptions, type DeploymentArtifact, DeploymentArtifactSchema, type DeploymentEnvironment, type DockerSshProviderConfig, HaiDeployError, type MiddlewareBackend, type MiddlewareField, type MiddlewareMode, type MiddlewareRequirement, type PortExposeConfig, ProviderConfigSchema, type ProvisionResult, type ScanResult, type ServiceType, type SshConfig, artifactChecksum, deploy, describeMiddlewareBackend, getDeployRecovery, loadDeploymentConfig, loadDeploymentEnvironment, readDeploymentArtifact, saveDeploymentEnvironment };
+export { DEPLOY_MIDDLEWARE, type DeployAppOptions, type DeployCommandState, type DeployConfig, type DeployConfigInput, DeployConfigSchema, type DeployCredentialOperations, type DeployError, type DeployFunctions, type DeployRecoveryInfo, type DeployResult, type DeployScanOptions, type DeploymentArtifact, DeploymentArtifactSchema, type DeploymentEnvironment, type DockerSshProviderConfig, HaiDeployError, type MiddlewareBackend, type MiddlewareField, type MiddlewareMode, type MiddlewareRequirement, type PortExposeConfig, ProviderConfigSchema, type ProvisionResult, type ScanResult, type ServiceType, type SshConfig, artifactChecksum, deploy, describeMiddlewareBackend, getDeployCommandState, getDeployRecovery, loadDeploymentConfig, loadDeploymentEnvironment, readDeploymentArtifact, saveDeploymentEnvironment };