@h-ai/deploy 0.1.0-alpha.64 → 0.1.0-alpha.66

package/dist/index.d.ts

@@ -2,6 +2,35 @@ import { z } from 'zod';
 import * as _h_ai_core from '@h-ai/core';
 import { HaiResult, HaiError } from '@h-ai/core';
 
+/** 镜像制品清单，例如 `{ version: 2, appVersion: '1.2.3', buildId: '1.2.3-build1', images: [{ name: 'app', file: 'app-1.2.3.tar', imageRef: 'localhost/demo:1.2.3-build1', sha256: '...' }] }`。 */
+declare const DeploymentArtifactSchema: z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    appVersion: z.ZodString;
+    buildId: z.ZodString;
+    images: z.ZodArray<z.ZodObject<{
+        name: z.ZodEnum<{
+            app: "app";
+            web: "web";
+        }>;
+        file: z.ZodString;
+        imageRef: z.ZodString;
+        sha256: z.ZodString;
+        containerPort: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** 构建器与部署器共享的镜像交付结构；参见 DeploymentArtifactSchema 示例。 */
+type DeploymentArtifact = z.infer<typeof DeploymentArtifactSchema>;
+/**
+ * 流式计算制品校验和，避免将大镜像一次性读入内存。
+ * @example `const checksum = await artifactChecksum("/release/app-1.2.3.tar")`
+ */
+declare function artifactChecksum(file: string): Promise<string>;
+/**
+ * 校验完整构建产物；缺失、损坏或非法清单均抛错，由部署边界转换为 HaiResult。
+ * @example `const artifact = await readDeploymentArtifact("/release/build-1")`
+ */
+declare function readDeploymentArtifact(directory: string): Promise<DeploymentArtifact>;
+
 /**
  * @h-ai/deploy — 部署配置 Schema
  *
@@ -28,7 +57,7 @@ declare const PortExposeSchema: z.ZodObject<{
 /** docker-ssh 部署平台配置 */
 declare const DockerSshProviderConfigSchema: z.ZodObject<{
     type: z.ZodLiteral<"docker-ssh">;
-    ssh: z.ZodObject<{
+    ssh: z.ZodOptional<z.ZodObject<{
         host: z.ZodString;
         port: z.ZodDefault<z.ZodNumber>;
         username: z.ZodString;
@@ -36,7 +65,7 @@ declare const DockerSshProviderConfigSchema: z.ZodObject<{
         knownHostsFile: z.ZodOptional<z.ZodString>;
         strictHostKeyChecking: z.ZodDefault<z.ZodBoolean>;
         connectTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip>;
+    }, z.core.$strip>>;
     remote: z.ZodDefault<z.ZodObject<{
         baseDir: z.ZodDefault<z.ZodString>;
         runtime: z.ZodDefault<z.ZodEnum<{
@@ -57,7 +86,7 @@ declare const ProviderConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     token: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"docker-ssh">;
-    ssh: z.ZodObject<{
+    ssh: z.ZodOptional<z.ZodObject<{
         host: z.ZodString;
         port: z.ZodDefault<z.ZodNumber>;
         username: z.ZodString;
@@ -65,7 +94,7 @@ declare const ProviderConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         knownHostsFile: z.ZodOptional<z.ZodString>;
         strictHostKeyChecking: z.ZodDefault<z.ZodBoolean>;
         connectTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip>;
+    }, z.core.$strip>>;
     remote: z.ZodDefault<z.ZodObject<{
         baseDir: z.ZodDefault<z.ZodString>;
         runtime: z.ZodDefault<z.ZodEnum<{
@@ -88,12 +117,13 @@ type PortExposeConfig = z.infer<typeof PortExposeSchema>;
 type DockerSshProviderConfig = z.infer<typeof DockerSshProviderConfigSchema>;
 /** 部署模块完整配置 Schema */
 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.ZodObject<{
+        ssh: z.ZodOptional<z.ZodObject<{
             host: z.ZodString;
             port: z.ZodDefault<z.ZodNumber>;
             username: z.ZodString;
@@ -101,7 +131,7 @@ declare const DeployConfigSchema: z.ZodObject<{
             knownHostsFile: z.ZodOptional<z.ZodString>;
             strictHostKeyChecking: z.ZodDefault<z.ZodBoolean>;
             connectTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
-        }, z.core.$strip>;
+        }, z.core.$strip>>;
         remote: z.ZodDefault<z.ZodObject<{
             baseDir: z.ZodDefault<z.ZodString>;
             runtime: z.ZodDefault<z.ZodEnum<{
@@ -146,10 +176,9 @@ declare const DeployConfigSchema: z.ZodObject<{
         }, z.core.$strip>], "provisioner">>;
     }, z.core.$strip>>;
     container: z.ZodOptional<z.ZodObject<{
-        runtime: z.ZodDefault<z.ZodEnum<{
-            auto: "auto";
-            docker: "docker";
-            podman: "podman";
+        s3Engine: z.ZodDefault<z.ZodEnum<{
+            rustfs: "rustfs";
+            minio: "minio";
         }>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
@@ -158,10 +187,61 @@ type DeployConfig = z.infer<typeof DeployConfigSchema>;
 /** 部署配置输入类型（用户输入） */
 type DeployConfigInput = z.input<typeof DeployConfigSchema>;
 
+/** 部署环境的加载和持久化；公开环境文件不保存真实凭据。 */
+
+/** 部署环境快照；例如 prod 的 targetValues 只来自 `.env.prod`，不包含基础/私有覆盖。 */
+interface DeploymentEnvironment {
+    /** 文件模式（dev/test/prod 或其他合法模式名）。 */
+    environment: string;
+    /** 环境文件的绝对目录。 */
+    envDir: string;
+    /** 合并后的部署变量，可能含私有值，不得直接记录日志。 */
+    values: Record<string, string>;
+    /** 仅目标环境文件显式声明的变量，用于判断能否“保持不变”。 */
+    targetValues: Record<string, string>;
+}
+/**
+ * 按部署环境解析配置；未选择的可选 Provisioner 缺少凭据时保留空值，选择完成后由 Schema 校验。
+ * 不修改 core 缓存或进程变量，不在 YAML 文本上拼接凭据。
+ * @param name - 模块配置名，例如 deploy/db/iam
+ * @param path - YAML 文件绝对路径
+ * @param values - 已加载的目标环境变量
+ * @returns 配置对象；解析错误已脱敏
+ * @example `loadDeploymentConfig('deploy', '/app/config/_deploy.yml', environment.values)`
+ */
+declare function loadDeploymentConfig(name: string, path: string, values: Record<string, string | undefined>): HaiResult<Record<string, unknown>>;
+/**
+ * 加载部署环境；指定环境文件缺失时返回错误并要求用户创建。
+ * @param options - 模式、环境目录与是否强制存在目标文件
+ * @param options.environment - dev/test/prod 或自定义模式
+ * @param options.envDir - 环境文件所在目录
+ * @param options.requireFile - 默认 true；扫描无显式环境时可只读取已有基础文件
+ * @returns 环境快照，可能包含私有值，不得直接输出
+ * @example `loadDeploymentEnvironment({ environment: 'prod', envDir: '.' })`
+ */
+declare function loadDeploymentEnvironment(options: {
+    environment: string;
+    envDir: string;
+    requireFile?: boolean;
+}): HaiResult<DeploymentEnvironment>;
+/**
+ * 保存部署产生的变量：公共值写目标环境文件，凭据写 `.env.local`。
+ * 返回实际写入的变量名，调用者只展示名称或脱敏值。
+ * @param environment - 已加载的目标环境快照
+ * @param values - 需要更新的变量；未提供的项保持原状
+ * @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 })`
+ */
+declare function saveDeploymentEnvironment(environment: DeploymentEnvironment, values: Record<string, string>, options?: {
+    private?: boolean;
+}): HaiResult<string[]>;
+
 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;
@@ -173,8 +253,6 @@ declare const HaiDeployError: {
     readonly UNSUPPORTED_TYPE: _h_ai_core.HaiErrorDef;
     readonly CONFIG_ERROR: _h_ai_core.HaiErrorDef;
     readonly CREDENTIAL_ERROR: _h_ai_core.HaiErrorDef;
-    readonly CONTAINER_RUNTIME_NOT_FOUND: _h_ai_core.HaiErrorDef;
-    readonly CONTAINER_BUILD_FAILED: _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;
@@ -203,14 +281,48 @@ interface DeployError {
     cause?: unknown;
 }
 /** 基础设施服务类型 */
-type ServiceType = 'db' | 'cache' | 'storage' | 'email' | 'sms' | 'vecdb';
+type ServiceType = 'db' | 'cache' | 'storage' | 'email' | 'sms' | 'vecdb' | 'ldap';
+/** 每项中间件的处理方式；keep 不修改配置，也不开通服务。 */
+type MiddlewareMode = 'default' | 'custom' | 'keep';
+/** 扫描环境；例如 `{ environment: 'test', envDir: '/workspace/app' }`。 */
+interface DeployScanOptions {
+    /** 环境文件模式。 */
+    environment?: string;
+    /** 环境文件目录；默认自动定位到应用或 workspace 根。 */
+    envDir?: string;
+}
+/** 依赖对应的中间件；例如 IAM 的 LDAP 位于 `iam.ldap`，可处于 disabled 状态。 */
+interface MiddlewareRequirement {
+    /** 中间件类别。 */
+    service: ServiceType;
+    /** 生效后端标识。 */
+    backend: string;
+    /** 检测来源（依赖包或配置名），用于解释为何需要此项。 */
+    source: string;
+    /** 模块配置名。 */
+    configName: string;
+    /** 模块配置内的路径；例如 LDAP 为 ['ldap']。 */
+    configPath: string[];
+    /** 约定变量前缀。 */
+    envPrefix: string;
+    /** 生效连接配置，可能含凭据，仅用于输入默认值，不得原样输出日志。 */
+    config: Record<string, unknown>;
+}
 /**
  * 应用扫描结果
  *
  * 由 scanner 分析应用目录后返回，描述应用的框架类型、依赖和部署需求。
  */
 interface ScanResult {
-    /** 应用名称（来自 package.json name） */
+    /** 调用者指定的部署目录，对应 lockfile 中的一个 importer。 */
+    appDir?: string;
+    /** 公共环境文件目录。 */
+    envDir?: string;
+    /** 依赖与配置共同确定的中间件详情。 */
+    middlewares?: MiddlewareRequirement[];
+    /** 从运行依赖图识别的 Hai 模块；peer 和开发依赖不启用模块。 */
+    haiModules?: string[];
+    /** 应用名称（目录名称；可用 projectName 显式覆盖部署资源名）。 */
     appName: string;
     /** 是否为 SvelteKit 项目 */
     isSvelteKit: boolean;
@@ -222,8 +334,6 @@ interface ScanResult {
     requiredServices: ServiceType[];
     /** 各服务检测到的后端类型（如 db→postgresql/mysql，vecdb→qdrant），用于生成匹配的 sidecar */
     serviceBackends: Partial<Record<ServiceType, string>>;
-    /** 构建命令 */
-    buildCommand: string;
 }
 /**
  * 部署结果
@@ -236,7 +346,11 @@ 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），容器部署时返回 */
@@ -275,12 +389,22 @@ interface DeployRecoveryInfo {
 }
 /** 部署选项 */
 interface DeployAppOptions {
-    /** 项目名称（默认从 package.json name 提取） */
+    /** 部署环境标识；显式指定时必须存在 .env.<environment>。 */
+    environment?: string;
+    /** 环境文件所在目录，默认自动定位。 */
+    envDir?: string;
+    /** 按服务或变量前缀选择处理方式；如 HAI_REACH_PROVIDERS_1 可独立于另一邮件连接。 */
+    serviceModes?: Partial<Record<string, MiddlewareMode>>;
+    /** 项目名称（默认使用明确指定的部署目录名称）。 */
     projectName?: string;
-    /** 是否跳过基础设施开通 */
-    skipProvision?: boolean;
-    /** 是否跳过构建 */
-    skipBuild?: boolean;
+    /** 是否跳过全部中间件配置与开通，默认 false；例如配置完备时设为 true。 */
+    skipMiddleware?: boolean;
+    /** 已构建镜像目录；默认最近构建入口/锁文件目录下的 .hai/build/docker。 */
+    artifactDir?: string;
+    /** 只生成部署 tar，不连接 SSH；仅 docker-ssh 支持。 */
+    bundleOnly?: boolean;
+    /** 部署 tar 输出路径；默认 .hai/deploy/<环境>/bundle-<项目>-<部署ID>-<版本>.tar，自定义文件名自动补 -<版本>。 */
+    output?: string;
 }
 /**
  * Deploy 凭证文件操作。
@@ -338,16 +462,16 @@ interface DeployFunctions {
      *
      * @param appDir - 应用根目录路径
      */
-    scan: (appDir: string) => Promise<HaiResult<ScanResult>>;
+    scan: (appDir: string, options?: DeployScanOptions) => Promise<HaiResult<ScanResult>>;
     /**
      * 对所有已配置的 Provisioner 执行基础设施开通
      *
      * @param projectName - 用于资源命名的项目名
      * @returns 所有 Provisioner 的结果列表
      */
-    provisionAll: (projectName: string) => Promise<HaiResult<ProvisionResult[]>>;
+    provisionAll: (projectName: string, services?: ServiceType[]) => Promise<HaiResult<ProvisionResult[]>>;
     /**
-     * 执行完整部署流程（provision → build → deploy）
+     * 部署已有构建产物（环境和中间件 → 打包 → 上传/启动）；不会调用构建命令。
      *
      * @param appDir - 应用根目录路径
      * @param options - 部署选项
@@ -376,7 +500,75 @@ interface DeployFunctions {
  */
 declare const deploy: DeployFunctions;
 
+/**
+ * @h-ai/deploy — i18n
+ *
+ * 本文件提供部署模块的 i18n 文案访问入口。
+ * @module deploy-i18n
+ */
+/**
+ * 获取部署模块文案
+ *
+ * @param key - 文案 Key
+ * @param options - 插值参数与格式化选项
+ * @returns 本地化后的文案字符串
+ *
+ * @example
+ * ```ts
+ * const text = deployM('deploy_notInitialized')
+ * ```
+ */
+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", options?: _h_ai_core.MessageOptions) => string;
+
+/**
+ * 部署中间件的后端与连接字段目录，供扫描、CLI 和容器规划共同使用。
+ * 字段名与对应模块公开 Schema 保持一致，不把模块依赖等同于必须创建外部服务。
+ * @module deploy-middleware
+ */
+
+/** 连接字段；例如 `{ name: 'port', defaultValue: '5432', 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'`。 */
+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 `DEPLOY_MIDDLEWARE.db.map(item => item.label)` 返回数据库选择项。
+ */
+declare const DEPLOY_MIDDLEWARE: Record<ServiceType, MiddlewareBackend[]>;
+/**
+ * 返回当前语言的后端用途说明。
+ * @example `describeMiddlewareBackend(DEPLOY_MIDDLEWARE.db[0])`
+ */
+declare function describeMiddlewareBackend(backend: MiddlewareBackend): string;
+
 /** 读取错误中的恢复清单；仅返回明确允许展示的字段。 */
 declare function getDeployRecovery(error: HaiError): DeployRecoveryInfo | undefined;
 
-export { type DeployAppOptions, type DeployConfig, type DeployConfigInput, DeployConfigSchema, type DeployCredentialOperations, type DeployError, type DeployFunctions, type DeployRecoveryInfo, type DeployResult, type DockerSshProviderConfig, HaiDeployError, type PortExposeConfig, ProviderConfigSchema, type ProvisionResult, type ScanResult, type ServiceType, type SshConfig, deploy, getDeployRecovery };
+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 };