@h-ai/deploy 0.1.0-alpha.18 → 0.1.0-alpha.20

package/README.md

@@ -18,6 +18,9 @@
 ```typescript
 import { deploy } from '@h-ai/deploy'
 
+// 可选：从 ~/.hai/credentials.yml 注入 HAI_DEPLOY_* 环境变量
+deploy.credentials.load()
+
 // 初始化
 await deploy.init({
   provider: { type: 'vercel', token: 'vel_xxx' },
@@ -59,13 +62,27 @@ services:
     apiKey: ${HAI_DEPLOY_UPSTASH_API_KEY}
 ```
 
+如需在脚本或 CLI 中显式管理凭证文件，请通过 `deploy.credentials.*` 访问：
+
+```typescript
+deploy.credentials.load()
+deploy.credentials.save('HAI_DEPLOY_VERCEL_TOKEN', 'vel_xxx')
+deploy.credentials.saveAll({
+  HAI_DEPLOY_NEON_API_KEY: 'neon_xxx',
+})
+```
+
+> `deploy.scan()` 与 `deploy.credentials.*()` 都是本地文件系统能力，不依赖 `deploy.init()`。
+
 ## 错误处理
 
 ```typescript
+import { HaiDeployError } from '@h-ai/deploy'
+
 const result = await deploy.deployApp('./apps/my-app')
 if (!result.success) {
   switch (result.error.code) {
-    case HaiDeployError.PROVIDER_AUTH_FAILED.code:
+    case HaiDeployError.AUTH_FAILED.code:
       // Vercel Token 无效
       break
     case HaiDeployError.BUILD_FAILED.code:
@@ -80,10 +97,11 @@ if (!result.success) {
 | 错误码                            | code             | 说明         |
 | --------------------------------- | ---------------- | ------------ |
 | `HaiDeployError.DEPLOY_FAILED`    | `hai:deploy:001` | 部署失败     |
-| `HaiDeployError.BUILD_FAILED`     | `hai:deploy:002` | 构建失败     |
-| `HaiDeployError.AUTH_FAILED`      | `hai:deploy:005` | 认证失败     |
-| `HaiDeployError.PROVISION_FAILED` | `hai:deploy:006` | 资源开通失败 |
+| `HaiDeployError.BUILD_FAILED`     | `hai:deploy:003` | 构建失败     |
+| `HaiDeployError.AUTH_FAILED`      | `hai:deploy:006` | 认证失败     |
+| `HaiDeployError.PROVISION_FAILED` | `hai:deploy:007` | 资源开通失败 |
 | `HaiDeployError.NOT_INITIALIZED`  | `hai:deploy:010` | 未初始化     |
+| `HaiDeployError.ENV_VAR_FAILED`   | `hai:deploy:011` | 环境变量失败 |
 
 ## 测试
 

package/dist/index.d.ts

@@ -51,66 +51,6 @@ type DeployConfig = z.infer<typeof DeployConfigSchema>;
 /** 部署配置输入类型（用户输入） */
 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
- */
-
-/**
- * 获取凭证文件路径
- *
- * @returns `~/.hai/credentials.yml` 的绝对路径
- */
-declare function getCredentialsPath(): string;
-/**
- * 加载全局凭证文件并注入到 process.env
- *
- * 读取 `~/.hai/credentials.yml` 中的所有键值对，
- * 将每个 key-value 设置到 `process.env` 中，
- * 使后续 core 配置加载时自动解析 `${HAI_DEPLOY_*}` 变量。
- *
- * @returns 成功返回加载的凭证键名列表
- *
- * @example
- * ```ts
- * const result = loadCredentials()
- * if (result.success) {
- *   console.log(`Loaded ${result.data.length} credentials`)
- * }
- * ```
- */
-declare function loadCredentials(): HaiResult<string[]>;
-/**
- * 保存单个凭证到全局凭证文件
- *
- * 读取已有凭证 → 合并新凭证 → 写回文件。已有同名 key 会被覆盖。
- *
- * @param key - 环境变量名（如 HAI_DEPLOY_VERCEL_TOKEN）
- * @param value - 凭证值
- *
- * @example
- * ```ts
- * saveCredential('HAI_DEPLOY_VERCEL_TOKEN', 'vel_xxx')
- * ```
- */
-declare function saveCredential(key: string, value: string): HaiResult<void>;
-/**
- * 批量保存凭证到全局凭证文件
- *
- * @param entries - 凭证键值对
- *
- * @example
- * ```ts
- * saveCredentials({
- *   HAI_DEPLOY_VERCEL_TOKEN: 'vel_xxx',
- *   HAI_DEPLOY_NEON_API_KEY: 'neon_xxx',
- * })
- * ```
- */
-declare function saveCredentials(entries: Record<string, string>): HaiResult<void>;
-
 declare const HaiDeployError: {
     readonly DEPLOY_FAILED: _h_ai_core.HaiErrorDef;
     readonly PROJECT_CREATE_FAILED: _h_ai_core.HaiErrorDef;
@@ -121,8 +61,8 @@ declare const HaiDeployError: {
     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;
@@ -198,69 +138,6 @@ interface ProvisionResult {
     /** 资源标识信息（如项目名、数据库名等），用于日志和展示 */
     resourceInfo: string;
 }
-/**
- * 部署平台 Provider 接口（Vercel / Cloudflare Pages 等）
- *
- * 通过工厂函数创建（如 `createVercelProvider()`），负责将构建产物部署到目标平台。
- */
-interface DeployProvider {
-    /** Provider 名称 */
-    readonly name: string;
-    /**
-     * 验证凭证有效性
-     *
-     * @param token - 平台 API Token
-     * @returns 用户信息摘要（如邮箱/用户名）
-     */
-    authenticate: (token: string) => Promise<HaiResult<string>>;
-    /**
-     * 创建平台项目（幂等：已存在则返回现有项目 ID）
-     *
-     * @param projectName - 项目名称
-     * @returns 项目 ID
-     */
-    createProject: (projectName: string) => Promise<HaiResult<string>>;
-    /**
-     * 批量设置项目环境变量
-     *
-     * @param projectId - 平台项目 ID
-     * @param envVars - 环境变量键值对
-     */
-    setEnvVars: (projectId: string, envVars: Record<string, string>) => Promise<HaiResult<void>>;
-    /**
-     * 上传构建产物并触发部署
-     *
-     * @param projectId - 平台项目 ID
-     * @param outputDir - 构建产物目录（如 .vercel/output/）
-     * @returns 部署结果
-     */
-    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 提取） */
@@ -270,12 +147,28 @@ interface DeployAppOptions {
     /** 是否跳过构建 */
     skipBuild?: boolean;
 }
+/**
+ * Deploy 凭证文件操作。
+ *
+ * 这些方法仅操作 `~/.hai/credentials.yml`，不依赖 `deploy.init()`。
+ */
+interface DeployCredentialOperations {
+    /** 获取凭证文件绝对路径。 */
+    getPath: () => string;
+    /** 加载凭证文件并注入 `process.env`。 */
+    load: () => HaiResult<string[]>;
+    /** 保存单个凭证。 */
+    save: (key: string, value: string) => HaiResult<void>;
+    /** 批量保存凭证。 */
+    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()` — 关闭模块
@@ -293,6 +186,8 @@ interface DeployAppOptions {
  * ```
  */
 interface DeployFunctions {
+    /** 全局部署凭证文件操作。 */
+    readonly credentials: DeployCredentialOperations;
     /** 初始化模块（加载配置、创建 Provider 和 Provisioner 实例） */
     init: (config: DeployConfigInput) => Promise<HaiResult<void>>;
     /** 关闭模块 */
@@ -302,7 +197,9 @@ interface DeployFunctions {
     /** 是否已初始化 */
     readonly isInitialized: boolean;
     /**
-     * 扫描应用目录，检测依赖和所需服务
+     * 扫描应用目录，检测依赖和所需服务。
+     *
+     * 这是纯文件系统分析能力，不依赖云端认证状态，可在 `deploy.init()` 之前调用。
      *
      * @param appDir - 应用根目录路径
      */
@@ -344,27 +241,4 @@ interface DeployFunctions {
  */
 declare const deploy: DeployFunctions;
 
-/**
- * @h-ai/deploy — 应用扫描器
- *
- * 扫描应用目录，检测框架类型、模块依赖和所需基础设施。
- * @module deploy-scanner
- */
-
-/**
- * 扫描应用目录，检测框架类型、模块依赖和所需基础设施
- *
- * @param appDir - 应用根目录绝对路径
- * @returns 扫描结果（ScanResult）
- *
- * @example
- * ```ts
- * const result = await scanApp('/path/to/my-app')
- * if (result.success) {
- *   const { appName, isSvelteKit, requiredServices } = result.data
- * }
- * ```
- */
-declare function scanApp(appDir: string): Promise<HaiResult<ScanResult>>;
-
-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 { type DeployAppOptions, type DeployConfig, type DeployConfigInput, DeployConfigSchema, type DeployCredentialOperations, type DeployError, type DeployFunctions, type DeployResult, HaiDeployError, ProviderConfigSchema, type ProvisionResult, type ScanResult, type ServiceType, deploy };