@h-ai/deploy 0.1.0-alpha9 → 1.0.0-beta.2

package/dist/index.d.ts

@@ -1,24 +1,264 @@
 import { z } from 'zod';
 import * as _h_ai_core from '@h-ai/core';
-import { HaiResult } from '@h-ai/core';
+import { HaiResult, HaiError } from '@h-ai/core';
+
+/**
+ * 镜像制品清单，例如 `{ version: 4, primaryService: 'serv', appVersion: '1.2.3', buildId: '1.2.3-build1', partial: false, hasWeb: false, images: [...] }`。
+ * 根目录制品保留格式4；非根目录使用格式5，强制旧部署器拒绝而非静默忽略挂载路径。
+ * 完整产物包含primaryService，hasWeb记录浏览器端拓扑；结构验证不能代替真实归档校验。
+ * @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.ZodUnion<readonly [z.ZodLiteral<4>, z.ZodLiteral<5>]>;
+    primaryService: z.ZodEnum<{
+        serv: "serv";
+        web: "web";
+    }>;
+    appVersion: z.ZodString;
+    buildId: z.ZodString;
+    partial: z.ZodDefault<z.ZodBoolean>;
+    hasWeb: z.ZodDefault<z.ZodBoolean>;
+    webBasePath: z.ZodOptional<z.ZodString>;
+    servContainerPort: z.ZodOptional<z.ZodNumber>;
+    webContainerPort: z.ZodOptional<z.ZodNumber>;
+    images: z.ZodArray<z.ZodObject<{
+        name: z.ZodEnum<{
+            serv: "serv";
+            web: "web";
+        }>;
+        file: z.ZodString;
+        imageRef: z.ZodString;
+        sha256: z.ZodString;
+        containerPort: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * 构建器与部署器共享的镜像交付结构；参见 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>;
+/**
+ * 流式计算制品校验和，避免将大镜像一次性读入内存。
+ * @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/serv-1.0.0.tar')
+ * ```
+ */
+declare function artifactChecksum(file: string): Promise<string>;
+/**
+ * 校验完整构建产物；缺失、损坏或非法清单均抛错，由部署边界转换为 HaiResult。
+ * @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
  */
 
-/** 部署平台配置联合类型（后续可扩展更多平台） */
+/** SSH 连接配置（docker-ssh Provider 使用 OpenSSH 客户端连接远程主机） */
+declare const SshConfigSchema: z.ZodObject<{
+    host: z.ZodString;
+    port: z.ZodDefault<z.ZodNumber>;
+    username: z.ZodString;
+    auth: z.ZodOptional<z.ZodEnum<{
+        key: "key";
+        password: "password";
+    }>>;
+    password: z.ZodOptional<z.ZodString>;
+    identityFile: z.ZodOptional<z.ZodString>;
+    knownHostsFile: z.ZodOptional<z.ZodString>;
+    strictHostKeyChecking: z.ZodDefault<z.ZodBoolean>;
+    connectTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/** 端口直出暴露配置 */
+declare const PortExposeSchema: z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"port">>;
+    containerPort: z.ZodDefault<z.ZodNumber>;
+    hostPort: z.ZodNumber;
+}, z.core.$strip>;
+/** docker-ssh 部署平台配置 */
+declare const DockerSshProviderConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"docker-ssh">;
+    ssh: z.ZodOptional<z.ZodObject<{
+        host: z.ZodString;
+        port: z.ZodDefault<z.ZodNumber>;
+        username: z.ZodString;
+        auth: z.ZodOptional<z.ZodEnum<{
+            key: "key";
+            password: "password";
+        }>>;
+        password: z.ZodOptional<z.ZodString>;
+        identityFile: z.ZodOptional<z.ZodString>;
+        knownHostsFile: z.ZodOptional<z.ZodString>;
+        strictHostKeyChecking: z.ZodDefault<z.ZodBoolean>;
+        connectTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    remote: z.ZodDefault<z.ZodObject<{
+        baseDir: z.ZodDefault<z.ZodString>;
+        runtime: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            docker: "docker";
+            podman: "podman";
+        }>>;
+    }, z.core.$strip>>;
+    expose: z.ZodObject<{
+        type: z.ZodDefault<z.ZodLiteral<"port">>;
+        containerPort: z.ZodDefault<z.ZodNumber>;
+        hostPort: z.ZodNumber;
+    }, z.core.$strip>;
+    trustedEdgeProxies: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6, z.ZodCIDRv4, z.ZodCIDRv6]>>>;
+}, 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;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"docker-ssh">;
+    ssh: z.ZodOptional<z.ZodObject<{
+        host: z.ZodString;
+        port: z.ZodDefault<z.ZodNumber>;
+        username: z.ZodString;
+        auth: z.ZodOptional<z.ZodEnum<{
+            key: "key";
+            password: "password";
+        }>>;
+        password: z.ZodOptional<z.ZodString>;
+        identityFile: z.ZodOptional<z.ZodString>;
+        knownHostsFile: z.ZodOptional<z.ZodString>;
+        strictHostKeyChecking: z.ZodDefault<z.ZodBoolean>;
+        connectTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    remote: z.ZodDefault<z.ZodObject<{
+        baseDir: z.ZodDefault<z.ZodString>;
+        runtime: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            docker: "docker";
+            podman: "podman";
+        }>>;
+    }, z.core.$strip>>;
+    expose: z.ZodObject<{
+        type: z.ZodDefault<z.ZodLiteral<"port">>;
+        containerPort: z.ZodDefault<z.ZodNumber>;
+        hostPort: z.ZodNumber;
+    }, z.core.$strip>;
+    trustedEdgeProxies: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6, z.ZodCIDRv4, z.ZodCIDRv6]>>>;
 }, z.core.$strip>], "type">;
-/** 部署模块完整配置 Schema */
+/**
+ * SSH 连接配置（parse 后）
+ * 这是 Schema 解析后的类型，默认字段已必填；auth 省略时非空密码选择 password，否则使用 ssh-agent/默认密钥；显式 key 忽略残留 password。
+ * @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 后）
+ * @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 后）
+ * 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
+ * @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<{
         type: z.ZodLiteral<"vercel">;
         token: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"docker-ssh">;
+        ssh: z.ZodOptional<z.ZodObject<{
+            host: z.ZodString;
+            port: z.ZodDefault<z.ZodNumber>;
+            username: z.ZodString;
+            auth: z.ZodOptional<z.ZodEnum<{
+                key: "key";
+                password: "password";
+            }>>;
+            password: z.ZodOptional<z.ZodString>;
+            identityFile: z.ZodOptional<z.ZodString>;
+            knownHostsFile: z.ZodOptional<z.ZodString>;
+            strictHostKeyChecking: z.ZodDefault<z.ZodBoolean>;
+            connectTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        remote: z.ZodDefault<z.ZodObject<{
+            baseDir: z.ZodDefault<z.ZodString>;
+            runtime: z.ZodDefault<z.ZodEnum<{
+                auto: "auto";
+                docker: "docker";
+                podman: "podman";
+            }>>;
+        }, z.core.$strip>>;
+        expose: z.ZodObject<{
+            type: z.ZodDefault<z.ZodLiteral<"port">>;
+            containerPort: z.ZodDefault<z.ZodNumber>;
+            hostPort: z.ZodNumber;
+        }, z.core.$strip>;
+        trustedEdgeProxies: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6, z.ZodCIDRv4, z.ZodCIDRv6]>>>;
     }, z.core.$strip>], "type">;
     services: z.ZodOptional<z.ZodObject<{
         db: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -32,113 +272,183 @@ declare const DeployConfigSchema: z.ZodObject<{
         }, z.core.$strip>], "provisioner">>;
         storage: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
             provisioner: z.ZodLiteral<"cloudflare-r2">;
+            accessKeyId: z.ZodString;
+            secretAccessKey: z.ZodString;
             accountId: z.ZodString;
             apiToken: z.ZodString;
         }, z.core.$strip>], "provisioner">>;
         email: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
             provisioner: z.ZodLiteral<"resend">;
+            from: z.ZodString;
             apiKey: z.ZodString;
         }, z.core.$strip>], "provisioner">>;
         sms: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
             provisioner: z.ZodLiteral<"aliyun">;
+            signName: z.ZodString;
             accessKeyId: z.ZodString;
             accessKeySecret: z.ZodString;
         }, z.core.$strip>], "provisioner">>;
     }, z.core.$strip>>;
+    container: z.ZodOptional<z.ZodObject<{
+        s3Engine: z.ZodDefault<z.ZodEnum<{
+            rustfs: "rustfs";
+            minio: "minio";
+        }>>;
+    }, 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>;
 
+/** 部署环境的加载和持久化；公开环境文件不保存真实凭据。 */
+
 /**
- * @h-ai/deploy — 凭证管理
- *
- * 管理全局凭证文件 `~/.hai/credentials.yml`。 CLI 在加载 `_deploy.yml` 之前调用 `loadCredentials()` 将凭证注入 process.env， 使 core 的 `interpolateEnv()` 能自动解析 `${HAI_DEPLOY_*}` 变量。
- * @module deploy-credentials
+ * 部署环境快照；例如 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;
+    /** 环境文件的绝对目录。 */
+    envDir: string;
+    /** 合并后的部署变量，可能含私有值，不得直接记录日志。 */
+    values: Record<string, string>;
+    /** 仅目标环境文件显式声明的变量，用于判断能否“保持不变”。 */
+    targetValues: Record<string, string>;
+}
 /**
- * 获取凭证文件路径
- *
- * @returns `~/.hai/credentials.yml` 的绝对路径
+ * 按来源归并环境变量；HAI 高层父配置清除旧叶，同层按父→叶处理。
+ * @param layers - 从低到高优先级的环境来源。
+ * @param prefix - 可选变量前缀，仅归并该模块。
+ * @returns 归并后的字面量环境变量，可能包含秘密。
+ * @example 模块内部上下文
+ * ```ts
+ * const env = mergeEnvironmentLayers([{ HAI_CACHE_TYPE: 'memory' }, { HAI_CACHE: '{"type":"redis"}' }])
+ * ```
  */
-declare function getCredentialsPath(): string;
+declare function mergeEnvironmentLayers(layers: Array<Record<string, string | undefined>>, prefix?: string): Record<string, string>;
 /**
- * 加载全局凭证文件并注入到 process.env
- *
- * 读取 `~/.hai/credentials.yml` 中的所有键值对，
- * 将每个 key-value 设置到 `process.env` 中，
- * 使后续 core 配置加载时自动解析 `${HAI_DEPLOY_*}` 变量。
- *
- * @returns 成功返回加载的凭证键名列表
- *
+ * 按部署环境解析配置；未选择的可选 Provisioner 缺少凭据时保留空值，选择完成后由 Schema 校验。
+ * hai.json 只读取对应的根分区；运行时模块继续读取 YAML。不修改 core 缓存或进程变量。
+ * @param name - 模块配置名，例如 deploy/db/iam
+ * @param path - hai.json 或运行时 YAML 文件的绝对路径
+ * @param values - 已加载的目标环境变量
+ * @returns 配置对象；解析错误已脱敏
  * @example
  * ```ts
- * const result = loadCredentials()
- * if (result.success) {
- *   console.log(`Loaded ${result.data.length} credentials`)
- * }
+ * 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()}/hai.json`, environment.data.values)
+ * if (!config.success) throw new Error(config.error.message)
+ * // 返回对象仍需经 DeployConfigSchema 或 deploy.init 验证。
  * ```
  */
-declare function loadCredentials(): HaiResult<string[]>;
+declare function loadDeploymentConfig(name: string, path: string, values: Record<string, string | undefined>): HaiResult<Record<string, unknown>>;
 /**
- * 保存单个凭证到全局凭证文件
- *
- * 读取已有凭证 → 合并新凭证 → 写回文件。已有同名 key 会被覆盖。
- *
- * @param key - 环境变量名（如 HAI_DEPLOY_VERCEL_TOKEN）
- * @param value - 凭证值
- *
+ * 加载部署环境；指定环境文件缺失时返回错误并要求用户创建。
+ * 部署目标按进程 > 模式私有 > 模式公共 > 旧全局私有 > 基础归并。
+ * 其它模块保留进程 > 模式私有 > 旧全局私有 > 模式公共 > 基础；targetValues 仅记录模式公共项。
+ * @param options - 模式、环境目录与是否强制存在目标文件
+ * @param options.environment - dev/test/prod 或自定义模式
+ * @param options.envDir - 环境文件所在目录
+ * @param options.requireFile - 默认 true；扫描无显式环境时可只读取已有基础文件
+ * @returns 环境快照，可能包含私有值，不得直接输出
  * @example
  * ```ts
- * saveCredential('HAI_DEPLOY_VERCEL_TOKEN', 'vel_xxx')
+ * 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 saveCredential(key: string, value: string): HaiResult<void>;
+declare function loadDeploymentEnvironment(options: {
+    environment: string;
+    envDir: string;
+    requireFile?: boolean;
+}): HaiResult<DeploymentEnvironment>;
 /**
- * 批量保存凭证到全局凭证文件
- *
- * @param entries - 凭证键值对
- *
+ * 保存部署变量：公共值写目标环境文件，凭据写 `.env.<environment>.local`；旧共享私有文件不删除。
+ * 返回实际写入的变量名，调用者只展示名称或脱敏值。
+ * @param environment - 已加载的目标环境快照
+ * @param values - 需要更新的变量；未提供的项保持原状
+ * @param options - private 为 true 时所有值只保存在本机；适用于 SSH 地址、端口及密钥路径
+ * @param options.private - 是否将全部值保存到选中模式的私有文件
+ * @returns 已保存的变量名或脱敏错误
  * @example
  * ```ts
- * saveCredentials({
- *   HAI_DEPLOY_VERCEL_TOKEN: 'vel_xxx',
- *   HAI_DEPLOY_NEON_API_KEY: 'neon_xxx',
- * })
+ * 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.prod.local，不能放公共环境文件。
  * ```
  */
-declare function saveCredentials(entries: Record<string, string>): HaiResult<void>;
+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;
-    readonly BUILD_FAILED: _h_ai_core.HaiErrorDef;
     readonly UPLOAD_FAILED: _h_ai_core.HaiErrorDef;
     readonly AUTH_REQUIRED: _h_ai_core.HaiErrorDef;
     readonly AUTH_FAILED: _h_ai_core.HaiErrorDef;
     readonly PROVISION_FAILED: _h_ai_core.HaiErrorDef;
     readonly ADAPTER_MISSING: _h_ai_core.HaiErrorDef;
     readonly SCAN_FAILED: _h_ai_core.HaiErrorDef;
-    readonly ENV_VAR_FAILED: _h_ai_core.HaiErrorDef;
     readonly NOT_INITIALIZED: _h_ai_core.HaiErrorDef;
+    readonly ENV_VAR_FAILED: _h_ai_core.HaiErrorDef;
     readonly UNSUPPORTED_TYPE: _h_ai_core.HaiErrorDef;
     readonly CONFIG_ERROR: _h_ai_core.HaiErrorDef;
     readonly CREDENTIAL_ERROR: _h_ai_core.HaiErrorDef;
+    readonly REMOTE_CONNECT_FAILED: _h_ai_core.HaiErrorDef;
+    readonly REMOTE_COMMAND_FAILED: _h_ai_core.HaiErrorDef;
+    readonly IMAGE_TRANSFER_FAILED: _h_ai_core.HaiErrorDef;
+    readonly HEALTH_CHECK_FAILED: _h_ai_core.HaiErrorDef;
 };
 /**
  * 部署错误接口
  *
- * 所有部署操作返回的错误都遵循此接口。
- *
+ * 用于组合错误定义、消息与可选 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 {
@@ -149,29 +459,110 @@ interface DeployError {
     /** 原始错误（可选） */
     cause?: unknown;
 }
-/** 基础设施服务类型 */
-type ServiceType = 'db' | 'cache' | 'storage' | 'email' | 'sms';
+/**
+ * 基础设施服务类型
+ * @example
+ * ```ts
+ * import type { ServiceType } from '@h-ai/deploy'
+ * const service: ServiceType = 'db'
+ * ```
+ */
+type ServiceType = 'db' | 'cache' | 'storage' | 'email' | 'sms' | 'vecdb' | 'ldap';
+/**
+ * 每项中间件的处理方式；keep 不修改配置，也不开通服务。
+ * @example
+ * ```ts
+ * import type { MiddlewareMode } from '@h-ai/deploy'
+ * const mode: MiddlewareMode = 'keep' // 复用已有服务，不修改连接配置或自动开通。
+ * ```
+ */
+type MiddlewareMode = 'default' | 'custom' | 'keep';
+/**
+ * 扫描环境；例如 `{ 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 状态。
+ * @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;
+    /** 生效后端标识。 */
+    backend: string;
+    /** 检测来源（依赖包或配置名），用于解释为何需要此项。 */
+    source: string;
+    /** 模块配置名。 */
+    configName: string;
+    /** 模块配置内的路径；例如 LDAP 为 ['ldap']。 */
+    configPath: string[];
+    /** 约定变量前缀。 */
+    envPrefix: string;
+    /** 生效连接配置，可能含凭据，仅用于输入默认值，不得原样输出日志。 */
+    config: Record<string, unknown>;
+}
 /**
  * 应用扫描结果
  *
  * 由 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 {
-    /** 应用名称（来自 package.json name） */
+    /** 调用者指定的部署目录，对应 lockfile 中的一个 importer。 */
+    appDir?: string;
+    /** 公共环境文件目录。 */
+    envDir?: string;
+    /** 依赖与配置共同确定的中间件详情。 */
+    middlewares?: MiddlewareRequirement[];
+    /** 从运行依赖图识别的 Hai 模块；peer 和开发依赖不启用模块。 */
+    haiModules?: string[];
+    /** 工程名称（工程根 package.json.name；缺失时报错）。 */
     appName: string;
     /** 是否为 SvelteKit 项目 */
     isSvelteKit: boolean;
     /** 目标平台 adapter 是否已安装（如 @sveltejs/adapter-vercel） */
     adapterInstalled: boolean;
+    /** 容器部署所需的 @sveltejs/adapter-node 是否已安装 */
+    nodeAdapterInstalled: boolean;
     /** 检测到的模块依赖需要的服务列表 */
     requiredServices: ServiceType[];
-    /** 构建命令 */
-    buildCommand: string;
+    /** 各服务检测到的后端类型（如 db→postgresql/mysql，vecdb→qdrant），用于生成匹配的 sidecar */
+    serviceBackends: Partial<Record<ServiceType, string>>;
 }
 /**
  * 部署结果
  *
  * 包含部署后的访问 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 */
@@ -179,16 +570,32 @@ interface DeployResult {
     /** 部署 ID */
     deploymentId: string;
     /** 部署状态 */
-    status: 'ready' | 'building' | 'error';
+    status: 'ready' | 'packaged' | 'building' | 'error';
+    /** Compose 部署 tar 的绝对路径；包含私有配置，应安全传输。 */
+    bundlePath?: string;
+    /** 手工搬运和启动说明；仅打包不代表服务器已运行。 */
+    instructions?: string;
     /** 已设置的环境变量名列表 */
     envVarsSet: string[];
+    /** 部署 Provider 名称（如 vercel / docker-ssh），容器部署时返回 */
+    provider?: string;
+    /** 健康检查结果：passed 表示 HTTP 探测成功，container-only 表示仅确认容器运行 */
+    healthCheck?: 'passed' | 'container-only' | 'skipped';
 }
 /**
  * 基础设施开通结果
  *
  * 由 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 */
+    resourceStatus: 'created' | 'reused';
     /** 服务类型 */
     serviceType: ServiceType;
     /** Provisioner 名称 */
@@ -199,130 +606,289 @@ interface ProvisionResult {
     resourceInfo: string;
 }
 /**
- * 部署平台 Provider 接口（Vercel / Cloudflare Pages 等）
+ * 部署失败后的安全恢复信息，不含环境变量值或原始异常。
+ * @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;
+    platformProjectId?: string;
+    resources: Array<{
+        serviceType: ServiceType;
+        provisionerName: string;
+        resourceInfo: string;
+        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;
+    /** 匹配终态中的恢复结果；passed 表示旧服务和 HTTP 验证通过，不包含业务数据回退。 */
+    remoteRecovery?: 'not-needed' | 'passed' | 'failed' | 'stopped';
+}
+/**
+ * 部署选项
+ * 仅更新指定服务时仍受完整/部分制品与首次部署约束；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: ['serv'], output: '.hai/deploy/shop.tar' }
+ * ```
+ */
+interface DeployAppOptions {
+    /** 接收实际执行阶段，用于终端进度显示；不包含凭据或配置原文。 */
+    onProgress?: (stage: 'packaging' | 'preflight' | 'images' | 'dependencies' | 'start' | 'health' | 'complete') => void;
+    /** 只更新指定的 Compose 服务；省略时完整制品部署全部，部分制品只部署其镜像。 */
+    selectedServices?: string[];
+    /** 打包中间件镜像所用的本地引擎，auto 优先 Podman。 */
+    runtime?: 'auto' | 'podman' | 'docker';
+    /** 部署环境标识；显式指定时必须存在 .env.<environment>。 */
+    environment?: string;
+    /** 环境文件所在目录，默认自动定位。 */
+    envDir?: string;
+    /** 按服务或变量前缀选择处理方式；如 HAI_REACH_PROVIDERS_1 可独立于另一邮件连接。 */
+    serviceModes?: Partial<Record<string, MiddlewareMode>>;
+    /** 是否跳过全部中间件配置与开通，默认 false；例如配置完备时设为 true。 */
+    skipMiddleware?: boolean;
+    /** 已构建镜像目录；默认最近构建入口/锁文件目录下的 .hai/build/docker。 */
+    artifactDir?: string;
+    /** 只生成独立交付目录（含 tar 和部署脚本），不连接 SSH；仅 docker-ssh 支持。 */
+    bundleOnly?: boolean;
+    /** 交付包命名路径；默认在 .hai/deploy/<环境>/bundle-<项目>-<部署ID>-<版本>/ 中输出同名 tar 和脚本，自定义 release.tar 输出 release-<版本>/release-<版本>.tar；已有目录拒绝覆盖。 */
+    output?: string;
+}
+/**
+ * Deploy 凭证文件操作。
  *
- * 通过工厂函数创建（如 `createVercelProvider()`），负责将构建产物部署到目标平台。
+ * 这些方法仅操作 `~/.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 DeployProvider {
-    /** Provider 名称 */
-    readonly name: string;
+interface DeployCredentialOperations {
     /**
-     * 验证凭证有效性
-     *
-     * @param token - 平台 API Token
-     * @returns 用户信息摘要（如邮箱/用户名）
+     * 获取凭证文件绝对路径。
+     * @example
+     * ```ts
+     * import { deploy } from '@h-ai/deploy'
+     * const path = deploy.credentials.getPath() // 当前用户的全局凭证文件。
+     * ```
      */
-    authenticate: (token: string) => Promise<HaiResult<string>>;
+    getPath: () => string;
     /**
-     * 创建平台项目（幂等：已存在则返回现有项目 ID）
-     *
-     * @param projectName - 项目名称
-     * @returns 项目 ID
+     * 加载凭证文件并补齐 `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 // 不输出被注入的值。
+     * ```
      */
-    createProject: (projectName: string) => Promise<HaiResult<string>>;
+    load: () => HaiResult<string[]>;
     /**
-     * 批量设置项目环境变量
-     *
-     * @param projectId - 平台项目 ID
-     * @param envVars - 环境变量键值对
+     * 保存单个凭证。
+     * @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)
+     * ```
      */
-    setEnvVars: (projectId: string, envVars: Record<string, string>) => Promise<HaiResult<void>>;
+    save: (key: string, value: string) => HaiResult<void>;
     /**
-     * 上传构建产物并触发部署
-     *
-     * @param projectId - 平台项目 ID
-     * @param outputDir - 构建产物目录（如 .vercel/output/）
-     * @returns 部署结果
+     * 批量保存凭证。
+     * @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)
+     * ```
      */
-    deploy: (projectId: string, outputDir: string) => Promise<HaiResult<DeployResult>>;
-}
-/**
- * 基础设施服务 Provisioner 接口（Neon / Upstash / R2 / Resend / Aliyun）
- *
- * 通过工厂函数创建（如 `createNeonProvisioner(config)`），负责开通/验证云服务。
- */
-interface ServiceProvisioner {
-    /** Provisioner 名称 */
-    readonly name: string;
-    /** 对应的服务类型 */
-    readonly serviceType: ServiceType;
-    /**
-     * 验证凭证有效性
-     *
-     * @param credentials - 凭证键值对
-     * @returns 账户标识信息
-     */
-    authenticate: (credentials: Record<string, string>) => Promise<HaiResult<string>>;
-    /**
-     * 开通/查找服务资源（幂等：按项目名查找已有资源）
-     *
-     * @param projectName - 项目名称，用作资源命名
-     * @returns 开通结果（含环境变量映射）
-     */
-    provision: (projectName: string) => Promise<HaiResult<ProvisionResult>>;
-}
-/** 部署选项 */
-interface DeployAppOptions {
-    /** 项目名称（默认从 package.json name 提取） */
-    projectName?: string;
-    /** 是否跳过基础设施开通 */
-    skipProvision?: boolean;
-    /** 是否跳过构建 */
-    skipBuild?: boolean;
+    saveAll: (entries: Record<string, string>) => HaiResult<void>;
 }
 /**
  * Deploy 模块功能接口
  *
  * 提供自动化部署的完整 API：
+ * - `deploy.credentials.*()` — 凭证文件读写（不依赖 init）
  * - `deploy.init()` — 初始化（加载配置、创建 Provider 和 Provisioner）
- * - `deploy.scan()` — 扫描应用依赖
+ * - `deploy.scan()` — 扫描应用依赖（纯文件系统能力，不依赖 init）
  * - `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 {
-    /** 初始化模块（加载配置、创建 Provider 和 Provisioner 实例） */
+    /** 全局部署凭证文件操作。 */
+    readonly credentials: DeployCredentialOperations;
+    /**
+     * 初始化模块（加载配置、创建 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;
     /** 是否已初始化 */
     readonly isInitialized: boolean;
     /**
-     * 扫描应用目录，检测依赖和所需服务
+     * 扫描应用目录，检测依赖和所需服务。
+     *
+     * 这是纯文件系统分析能力，不依赖云端认证状态，可在 `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) => Promise<HaiResult<ScanResult>>;
+    scan: (appDir: string, options?: DeployScanOptions) => Promise<HaiResult<ScanResult>>;
     /**
      * 对所有已配置的 Provisioner 执行基础设施开通
      *
      * @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) => Promise<HaiResult<ProvisionResult[]>>;
+    provisionAll: (projectName: string, services?: ServiceType[]) => Promise<HaiResult<ProvisionResult[]>>;
     /**
-     * 执行完整部署流程（provision → build → deploy）
+     * 部署已有构建产物（环境和中间件 → 打包 → 上传/启动）；不会调用构建命令。
      *
      * @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>>;
 }
 
+/**
+ * @h-ai/deploy — 部署辅助函数
+ *
+ * 包含已有产物目录解析等与部署流程相关的辅助操作。 从 deploy-main.ts 中提取，遵循 main 仅做生命周期管理的规范。
+ * @module deploy-functions
+ */
+
+/**
+ * 将工程根 package.json.name 归一化为镜像与部署资源共用的身份；移除 scope、转小写并合并非法字符。
+ * @throws Error - 名称为空或归一化后不含字母数字。
+ * @param name - 工程根 package.json.name。
+ * @returns 可用于 OCI 镜像和 Compose 资源的工程名。
+ * @example
+ * ```ts
+ * import { normalizeProjectName } from '@h-ai/deploy'
+ * const name = normalizeProjectName('@shop/orders')
+ * ```
+ */
+declare function normalizeProjectName(name: string): string;
+
 /**
  * @h-ai/deploy — 模块主入口
  *
@@ -332,39 +898,262 @@ 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;
 
 /**
- * @h-ai/deploy — 应用扫描器
+ * @h-ai/deploy — i18n
  *
- * 扫描应用目录，检测框架类型、模块依赖和所需基础设施。
- * @module deploy-scanner
+ * 本文件提供部署模块的 i18n 文案访问入口。
+ * @module deploy-i18n
  */
+/**
+ * 获取部署模块文案
+ * 使用 core 请求/全局 locale 的现有中英字典；不自行缓存调用时的语言。
+ * @param key - 文案 Key
+ * @param options - 插值参数与格式化选项
+ * @returns 本地化后的文案字符串
+ * @example 模块内部上下文
+ * ```ts
+ * 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_webBaseConflict" | "deploy_storageProxyInvalid" | "deploy_storagePublicEndpointInvalid" | "deploy_storageBackendRequired" | "deploy_artifactInvalid" | "deploy_sshRequired" | "deploy_sshPasswordInvalid" | "deploy_sshAskpassFailed" | "deploy_sshAskpassCleanupFailed" | "deploy_targetAuth" | "deploy_targetPasswordEnv" | "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_imageVersionRequired" | "deploy_bundleRuntimeRequired" | "deploy_bundleFailed" | "deploy_configFileInvalid" | "deploy_configFileUnreadable" | "deploy_bundleNameInvalid" | "deploy_localStopped" | "deploy_localUnknown" | "deploy_localNotStarted" | "deploy_commandOutputFailed" | "deploy_commandInputFailed" | "deploy_commandTreeActive" | "deploy_commandExecutionFailed" | "deploy_remoteUnknown" | "deploy_remoteFinished" | "deploy_bundleDirectoryExists" | "deploy_bundleFull" | "deploy_bundlePartial" | "deploy_bundleSelection" | "deploy_transportBodyLimitInvalid" | "deploy_transportKeyRingInvalid" | "deploy_uploadPasswordPrompt" | "deploy_uploadPasswordUnavailable" | "deploy_uploadPasswordCancelled" | "deploy_uploadPasswordInvalid" | "deploy_managedSecretsInvalid" | "deploy_secretImportFailed" | "deploy_projectNameRequired" | "deploy_projectNameOverrideRemoved" | "deploy_requestAccessInvalid", options?: _h_ai_core.MessageOptions) => string;
 
 /**
- * 扫描应用目录，检测框架类型、模块依赖和所需基础设施
- *
- * @param appDir - 应用根目录绝对路径
- * @returns 扫描结果（ScanResult）
- *
+ * 部署中间件的后端与连接字段目录，供扫描、CLI 和容器规划共同使用。
+ * 字段名与对应模块公开 Schema 保持一致，不把模块依赖等同于必须创建外部服务。
+ * @module deploy-middleware
+ */
+
+/**
+ * 连接字段；例如 `{ 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;
+    /** 无现有配置时使用的提示默认值。 */
+    defaultValue?: string;
+    /** 是否为连接所必需；可选项允许留空。 */
+    required?: boolean;
+    /** 密码输入与私有环境文件写入标记。 */
+    secret?: boolean;
+    /** 交互校验类型；端口范围为 1–65535。 */
+    kind?: 'port' | 'boolean' | 'number' | 'url';
+    /** 数值下限；未声明时为 0。 */
+    minimum?: number;
+    /** 数值上限；例如 Redis db 为 15。 */
+    maximum?: number;
+}
+/**
+ * 后端目录项；例如 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;
+    /** 可直接识别的产品名称。 */
+    label: string;
+    /** 用途说明的 i18n 消息键。 */
+    purpose: Parameters<typeof deployM>[0];
+    /** 云自动开通器；缺失表示不能自动开通该云服务。 */
+    provisioner?: 'neon' | 'upstash' | 'cloudflare-r2' | 'resend' | 'aliyun';
+    /** 自定义连接需要逐项输入的字段。 */
+    fields: MiddlewareField[];
+}
+/**
+ * 所有可部署中间件的连接目录。
+ * SQLite、memory、local 与 disabled 保留本地/禁用语义，不创建无关 sidecar。
+ * 目录同时描述本机、禁用、自建与云后端；存在依赖不等于必须开通新资源。
  * @example
  * ```ts
- * const result = await scanApp('/path/to/my-app')
- * if (result.success) {
- *   const { appName, isSvelteKit, requiredServices } = result.data
+ * 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[]>;
+/**
+ * 返回当前语言的后端用途说明。
+ * @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;
+
+/**
+ * 查看与执行入口相同的扫描、环境、项目身份和制品校验结果。远端 current 只报告为待执行时核验。
+ * @example
+ * ```ts
+ * import { createDeploymentPlan } from '@h-ai/deploy'
+ * const plan = await createDeploymentPlan('/workspace/shop', { provider: { type: 'docker-ssh', expose: { hostPort: 8080 } } }, { environment: 'prod' })
+ * ```
+ */
+declare function createDeploymentPlan(appDir: string, input: DeployConfigInput, options?: DeployAppOptions & {
+    inspectRemote?: boolean;
+}): Promise<{
+    success: false;
+    error: _h_ai_core.HaiError;
+} | {
+    success: true;
+    data: {
+        projectName: string;
+        root: string;
+        appDir: string;
+        environment: string;
+        target: {
+            provider: "docker-ssh";
+            host: string | undefined;
+            port: number | undefined;
+            directory: string | undefined;
+            runtime: "auto" | "docker" | "podman";
+            hostPort: number;
+        } | {
+            provider: "vercel";
+            host?: undefined;
+            port?: undefined;
+            directory?: undefined;
+            runtime?: undefined;
+            hostPort?: undefined;
+        };
+        artifact: {
+            directory: string;
+            version: string;
+            buildId: string;
+            verified: boolean;
+            images: {
+                name: "serv" | "web";
+                reference: string;
+                sha256: string;
+            }[];
+        } | undefined;
+        selected: string[];
+        retained: string[];
+        containers: string[];
+        composeManagedServices: string[];
+        logicalVolumes: string[];
+        middleware: {
+            service: ServiceType;
+            backend: string;
+            configuration: string;
+            action: MiddlewareMode;
+            provisioner: string | undefined;
+        }[];
+        configuration: {
+            files: string[];
+            environmentKeys: string[];
+        };
+        baseline: {
+            required: boolean;
+            state: string;
+            current: string | undefined;
+            release: string | undefined;
+        };
+        recovery: {
+            releases: string | undefined;
+            point: string;
+            preservesVolumes: boolean;
+            databaseRollback: boolean;
+        };
+    };
+}>;
+
+/**
+ * 读取命令失败的安全状态；不把本地 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 scanApp(appDir: string): Promise<HaiResult<ScanResult>>;
+declare function getDeployRecovery(error: HaiError): DeployRecoveryInfo | undefined;
+
+/** 旧部署凭据的显式、只读预检与原子导入；不轮换密码、不变更容器和数据卷。 */
+
+/**
+ * 在目标服务器导入前核验旧凭据；dryRun 默认 true，apply 需要 Linux flock 与运行中的原服务。
+ * 输入文件必须由操作者明确指定，权限 0600；API 不读取旧部署包猜测密码。
+ * @param options - 服务器项目目录、受保护的导入 JSON、容器引擎和只读开关。
+ * @param options.directory - 目标 Linux 服务器上已存在的项目部署目录。
+ * @param options.inputFile - 操作者提供的版本化私有 JSON 文件路径。
+ * @param options.runtime - 实际使用的 Docker 或 Podman 引擎。
+ * @param options.dryRun - 默认 true；只有显式 false 才在部署锁内保存状态。
+ * @returns 仅包含项目、凭据组和卷名的回执，不包含密码；失败不推进 current 或改变服务。
+ * @example
+ * ```ts
+ * import { importDeploymentSecrets } from '@h-ai/deploy'
+ * const plan = await importDeploymentSecrets({ directory: '/opt/hai/apps/shop-test', inputFile: '/private/shop-import.json', runtime: 'docker' })
+ * if (!plan.success) throw new Error(plan.error.message)
+ * // 停止业务写入、备份数据后，用相同输入显式传 dryRun: false 导入。
+ * ```
+ */
+declare function importDeploymentSecrets(options: {
+    directory: string;
+    inputFile: string;
+    runtime: 'docker' | 'podman';
+    dryRun?: boolean;
+}): Promise<HaiResult<{
+    projectName: string;
+    stateVersion: 2;
+    groups: string[];
+    volumes: string[];
+    changed: boolean;
+}>>;
 
-export { type DeployAppOptions, type DeployConfig, type DeployConfigInput, DeployConfigSchema, type DeployError, type DeployFunctions, type DeployProvider, type DeployResult, HaiDeployError, ProviderConfigSchema, type ProvisionResult, type ScanResult, type ServiceProvisioner, type ServiceType, deploy, getCredentialsPath, loadCredentials, saveCredential, saveCredentials, scanApp };
+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, createDeploymentPlan, deploy, describeMiddlewareBackend, getDeployCommandState, getDeployRecovery, importDeploymentSecrets, loadDeploymentConfig, loadDeploymentEnvironment, mergeEnvironmentLayers, normalizeProjectName, readDeploymentArtifact, saveDeploymentEnvironment };