fe-build-cli 1.1.0

package/src/git-branch.js

@@ -0,0 +1,259 @@
+import { execSync } from 'node:child_process';
+
+/**
+ * Git 分支管理模块
+ * 支持当前分支发布和主分支发布两种模式
+ */
+
+/**
+ * 获取当前 Git 分支名称
+ * @returns {string} 当前分支名
+ */
+export function getCurrentBranch() {
+  try {
+    return execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf-8' }).trim();
+  } catch (error) {
+    console.error('❌ 获取当前分支失败:', error.message);
+    throw new Error('无法获取当前分支，请确保在 Git 仓库中执行');
+  }
+}
+
+/**
+ * 获取 Git 提交 SHA（短格式）
+ * @returns {string} 短 SHA
+ */
+export function getGitSha() {
+  try {
+    return execSync('git rev-parse --short HEAD', { encoding: 'utf-8' }).trim();
+  } catch (error) {
+    return 'local';
+  }
+}
+
+/**
+ * 检查工作区是否干净
+ * @returns {boolean} 是否干净
+ */
+export function isWorkingTreeClean() {
+  try {
+    const status = execSync('git status --porcelain', { encoding: 'utf-8' }).trim();
+    return status === '';
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * 检查是否有未提交的更改
+ * @returns {{ clean: boolean, changes: string[] }} 状态信息
+ */
+export function checkUncommittedChanges() {
+  try {
+    const status = execSync('git status --porcelain', { encoding: 'utf-8' }).trim();
+    if (status === '') {
+      return { clean: true, changes: [] };
+    }
+    const changes = status.split('\n').filter(line => line.trim());
+    return { clean: false, changes };
+  } catch (error) {
+    return { clean: false, changes: [error.message] };
+  }
+}
+
+/**
+ * 切换到指定分支
+ * @param {string} branchName - 分支名
+ */
+export function checkoutBranch(branchName) {
+  try {
+    console.log(`\n📌 切换到分支: ${branchName}`);
+    execSync(`git checkout ${branchName}`, { stdio: 'inherit' });
+    console.log(`✅ 已切换到 ${branchName}`);
+  } catch (error) {
+    throw new Error(`切换到分支 ${branchName} 失败: ${error.message}`);
+  }
+}
+
+/**
+ * 拉取远程分支最新代码
+ * @param {string} branchName - 分支名
+ */
+export function pullBranch(branchName) {
+  try {
+    console.log(`\n📥 拉取 ${branchName} 最新代码...`);
+    execSync(`git pull origin ${branchName}`, { stdio: 'inherit' });
+    console.log(`✅ ${branchName} 已更新`);
+  } catch (error) {
+    console.warn(`⚠️ 拉取 ${branchName} 失败，继续执行...`);
+  }
+}
+
+/**
+ * 合并分支
+ * @param {string} sourceBranch - 源分支
+ * @param {string} targetBranch - 目标分支（当前所在分支）
+ * @returns {boolean} 是否成功
+ */
+export function mergeBranch(sourceBranch, targetBranch) {
+  try {
+    console.log(`\n🔀 合并 ${sourceBranch} 到 ${targetBranch}...`);
+    execSync(`git merge ${sourceBranch} --no-edit`, { stdio: 'inherit' });
+    console.log(`✅ 合并成功`);
+    return true;
+  } catch (error) {
+    console.error(`❌ 合并失败: ${error.message}`);
+    // 尝试中止合并
+    try {
+      execSync('git merge --abort', { stdio: 'inherit' });
+      console.log('已中止合并');
+    } catch (e) {
+      // 忽略
+    }
+    return false;
+  }
+}
+
+/**
+ * 推送分支到远程
+ * @param {string} branchName - 分支名
+ */
+export function pushBranch(branchName) {
+  try {
+    console.log(`\n📤 推送 ${branchName} 到远程...`);
+    execSync(`git push origin ${branchName}`, { stdio: 'inherit' });
+    console.log(`✅ 推送成功`);
+  } catch (error) {
+    throw new Error(`推送 ${branchName} 失败: ${error.message}`);
+  }
+}
+
+/**
+ * 执行主分支发布流程
+ * 流程：当前分支 -> 测试分支 -> 主分支
+ * @param {object} config - 分支配置
+ * @param {string} config.testBranch - 测试分支名
+ * @param {string} config.mainBranch - 主分支名
+ * @param {boolean} config.pushToRemote - 是否推送到远程
+ * @returns {object} 执行结果
+ */
+export function executeMainBranchFlow(config) {
+  const { testBranch, mainBranch, pushToRemote = true } = config;
+  const originalBranch = getCurrentBranch();
+
+  console.log('\n========================================');
+  console.log('  🌿 主分支发布流程');
+  console.log('========================================');
+  console.log(`当前分支: ${originalBranch}`);
+  console.log(`测试分支: ${testBranch}`);
+  console.log(`主分支: ${mainBranch}`);
+  console.log('========================================');
+
+  // 检查工作区状态
+  const { clean, changes } = checkUncommittedChanges();
+  if (!clean) {
+    console.error('❌ 工作区有未提交的更改:');
+    changes.forEach(change => console.log(`  ${change}`));
+    throw new Error('请先提交或暂存更改后再执行发布');
+  }
+
+  try {
+    // 步骤1: 切换到测试分支并拉取最新代码
+    checkoutBranch(testBranch);
+    pullBranch(testBranch);
+
+    // 步骤2: 合并当前分支到测试分支
+    if (!mergeBranch(originalBranch, testBranch)) {
+      throw new Error(`合并 ${originalBranch} 到 ${testBranch} 失败`);
+    }
+
+    // 步骤3: 推送测试分支（可选）
+    if (pushToRemote) {
+      pushBranch(testBranch);
+    }
+
+    // 步骤4: 切换到主分支并拉取最新代码
+    checkoutBranch(mainBranch);
+    pullBranch(mainBranch);
+
+    // 步骤5: 合并测试分支到主分支
+    if (!mergeBranch(testBranch, mainBranch)) {
+      throw new Error(`合并 ${testBranch} 到 ${mainBranch} 失败`);
+    }
+
+    // 步骤6: 推送主分支（可选）
+    if (pushToRemote) {
+      pushBranch(mainBranch);
+    }
+
+    console.log('\n========================================');
+    console.log('✅ 主分支发布流程完成');
+    console.log(`当前分支: ${mainBranch}`);
+    console.log('========================================');
+
+    return {
+      success: true,
+      originalBranch,
+      currentBranch: mainBranch,
+      testBranch,
+      mainBranch
+    };
+  } catch (error) {
+    // 出错时尝试切回原分支
+    try {
+      checkoutBranch(originalBranch);
+    } catch (e) {
+      // 忽略
+    }
+    throw error;
+  }
+}
+
+/**
+ * 执行当前分支发布流程
+ * 不切换分支，直接在当前分支发布
+ * @returns {object} 执行结果
+ */
+export function executeCurrentBranchFlow() {
+  const currentBranch = getCurrentBranch();
+  const gitSha = getGitSha();
+
+  console.log('\n========================================');
+  console.log('  🌿 当前分支发布模式');
+  console.log('========================================');
+  console.log(`当前分支: ${currentBranch}`);
+  console.log(`提交 SHA: ${gitSha}`);
+  console.log('========================================');
+
+  return {
+    success: true,
+    originalBranch: currentBranch,
+    currentBranch,
+    gitSha
+  };
+}
+
+/**
+ * 发布后切回原分支
+ * @param {string} originalBranch - 原分支名
+ */
+export function restoreBranch(originalBranch) {
+  const currentBranch = getCurrentBranch();
+  if (currentBranch !== originalBranch) {
+    console.log(`\n📌 切回原分支: ${originalBranch}`);
+    checkoutBranch(originalBranch);
+  }
+}
+
+export default {
+  getCurrentBranch,
+  getGitSha,
+  isWorkingTreeClean,
+  checkUncommittedChanges,
+  checkoutBranch,
+  pullBranch,
+  mergeBranch,
+  pushBranch,
+  executeMainBranchFlow,
+  executeCurrentBranchFlow,
+  restoreBranch
+};

package/src/index.d.ts

@@ -0,0 +1,330 @@
+/**
+ * fe-build-cli 类型定义
+ */
+
+/**
+ * 服务器配置
+ */
+export interface ServerConfig {
+  /** SSH 服务器地址 */
+  sshHost: string;
+  /** SSH 用户名 */
+  sshUser: string;
+  /** SSH 私钥路径 */
+  sshKeyPath: string;
+  /** SSH 端口（默认 22） */
+  sshPort?: number;
+  /** 部署后的访问地址 */
+  deployUrl: string;
+  /** 备份目录 */
+  backupDir: string;
+  /** 部署目录 */
+  deployDir: string;
+  /** 备份文件前缀 */
+  backupPrefix: string;
+  /** 构建模式：production 或 test */
+  buildMode?: 'production' | 'test';
+  /** 自定义构建命令 */
+  buildCommand?: string;
+  /** 需要保护的目录（部署时不会被删除） */
+  protectedDirs?: string[];
+}
+
+/**
+ * 分支配置
+ */
+export interface BranchesConfig {
+  /** 测试分支名 */
+  test: string;
+  /** 主分支名 */
+  main: string;
+}
+
+/**
+ * 钉钉通知配置
+ */
+export interface DingtalkConfig {
+  /** 钉钉机器人 webhook URL */
+  webhook: string;
+  /** 是否启用钉钉通知，默认 true */
+  enabled?: boolean;
+}
+
+/**
+ * fe-build-cli 配置
+ */
+export interface FeBuildConfig {
+  /** 分支配置 */
+  branches?: BranchesConfig;
+  /** 发布模式：main（主分支发布）或 current（当前分支发布） */
+  deployMode?: 'main' | 'current';
+  /** 钉钉通知配置 */
+  dingtalk?: DingtalkConfig;
+  /** 服务器配置 */
+  servers: Record<string, ServerConfig>;
+  /** 备份保留数量 */
+  backupRetentionCount?: number;
+}
+
+/**
+ * 部署选项
+ */
+export interface DeployOptions {
+  /** 环境名称 */
+  environment: string;
+  /** 环境配置 */
+  envConfig: ServerConfig;
+  /** 构建版本 */
+  buildVersion: string;
+  /** 是否跳过构建 */
+  skipBuild?: boolean;
+  /** 是否跳过本地清理 */
+  skipLocalCleanup?: boolean;
+}
+
+/**
+ * 回滚选项
+ */
+export interface RollbackOptions {
+  /** 环境名称 */
+  environment: string;
+  /** 环境配置 */
+  envConfig: ServerConfig;
+  /** 指定版本（可选） */
+  specifiedVersion?: string;
+}
+
+/**
+ * 主分支发布流程选项
+ */
+export interface MainBranchFlowOptions {
+  /** 测试分支名 */
+  testBranch: string;
+  /** 主分支名 */
+  mainBranch: string;
+  /** 是否推送到远程 */
+  pushToRemote?: boolean;
+}
+
+/**
+ * 分支流程执行结果
+ */
+export interface BranchFlowResult {
+  /** 是否成功 */
+  success: boolean;
+  /** 原始分支 */
+  originalBranch: string;
+  /** 当前分支 */
+  currentBranch: string;
+  /** 测试分支（主分支模式） */
+  testBranch?: string;
+  /** 主分支（主分支模式） */
+  mainBranch?: string;
+  /** Git SHA（当前分支模式） */
+  gitSha?: string;
+}
+
+/**
+ * SSH 客户端类
+ */
+export class SSHClient {
+  constructor(config: ServerConfig);
+  connect(): Promise<void>;
+  execCommand(command: string): Promise<string>;
+  uploadFile(localPath: string, remotePath: string): Promise<void>;
+  disconnect(): Promise<void>;
+}
+
+/**
+ * 部署函数
+ */
+export function deployToServer(options: DeployOptions): Promise<void>;
+
+/**
+ * 回滚函数
+ */
+export function rollbackDeployment(options: RollbackOptions): Promise<void>;
+
+/**
+ * 构建项目
+ */
+export function buildProject(envConfig: ServerConfig, buildVersion: string): void;
+
+/**
+ * 验证构建输出
+ */
+export function verifyBuildOutput(skipBuild: boolean): void;
+
+/**
+ * 压缩构建产物
+ */
+export function compressBuild(localZipFile: string, skipBuild: boolean): void;
+
+/**
+ * 备份现有部署
+ */
+export function backupExistingDeployment(options: {
+  ssh: SSHClient;
+  envConfig: ServerConfig;
+  buildVersion: string;
+  skipBuild: boolean;
+}): Promise<void>;
+
+/**
+ * 上传构建产物
+ */
+export function uploadBuild(
+  ssh: SSHClient,
+  localZipFile: string,
+  remoteZipFile: string,
+  skipBuild: boolean
+): Promise<void>;
+
+/**
+ * 清理部署目录并解压新版本
+ */
+export function deployAndExtract(options: {
+  ssh: SSHClient;
+  envConfig: ServerConfig;
+  remoteZipFile: string;
+  skipBuild: boolean;
+}): Promise<void>;
+
+/**
+ * 清理临时文件
+ */
+export function cleanupFiles(options: {
+  ssh: SSHClient;
+  remoteZipFile: string;
+  localZipFile: string;
+  skipLocalCleanup: boolean;
+  skipBuild: boolean;
+}): Promise<void>;
+
+/**
+ * 获取当前 Git 分支名称
+ */
+export function getCurrentBranch(): string;
+
+/**
+ * 获取 Git 提交 SHA（短格式）
+ */
+export function getGitSha(): string;
+
+/**
+ * 检查工作区是否干净
+ */
+export function isWorkingTreeClean(): boolean;
+
+/**
+ * 检查是否有未提交的更改
+ */
+export function checkUncommittedChanges(): { clean: boolean; changes: string[] };
+
+/**
+ * 切换到指定分支
+ */
+export function checkoutBranch(branchName: string): void;
+
+/**
+ * 拉取远程分支最新代码
+ */
+export function pullBranch(branchName: string): void;
+
+/**
+ * 合并分支
+ */
+export function mergeBranch(sourceBranch: string, targetBranch: string): boolean;
+
+/**
+ * 推送分支到远程
+ */
+export function pushBranch(branchName: string): void;
+
+/**
+ * 执行主分支发布流程
+ */
+export function executeMainBranchFlow(config: MainBranchFlowOptions): BranchFlowResult;
+
+/**
+ * 执行当前分支发布流程
+ */
+export function executeCurrentBranchFlow(): BranchFlowResult;
+
+/**
+ * 发布后切回原分支
+ */
+export function restoreBranch(originalBranch: string): void;
+
+/**
+ * 钉钉通知结果
+ */
+export interface DingtalkResult {
+  success: boolean;
+  data?: any;
+  error?: string;
+}
+
+/**
+ * 部署成功通知选项
+ */
+export interface DeploySuccessNotificationOptions {
+  environment: string;
+  buildVersion: string;
+  serverHost: string;
+  deployUrl: string;
+  branch: string;
+  deployMode: string;
+  duration?: string;
+}
+
+/**
+ * 部署失败通知选项
+ */
+export interface DeployFailureNotificationOptions {
+  environment: string;
+  buildVersion?: string;
+  serverHost: string;
+  branch: string;
+  error: string;
+}
+
+/**
+ * 回滚通知选项
+ */
+export interface RollbackNotificationOptions {
+  environment: string;
+  backupFile: string;
+  serverHost: string;
+  deployUrl: string;
+  success: boolean;
+}
+
+/**
+ * 发送钉钉消息
+ */
+export function sendDingTalkMessage(webhookUrl: string, message: any): Promise<DingtalkResult>;
+
+/**
+ * 发送部署成功通知
+ */
+export function sendDeploySuccessNotification(
+  webhookUrl: string,
+  options: DeploySuccessNotificationOptions
+): Promise<DingtalkResult>;
+
+/**
+ * 发送部署失败通知
+ */
+export function sendDeployFailureNotification(
+  webhookUrl: string,
+  options: DeployFailureNotificationOptions
+): Promise<DingtalkResult>;
+
+/**
+ * 发送回滚通知
+ */
+export function sendRollbackNotification(
+  webhookUrl: string,
+  options: RollbackNotificationOptions
+): Promise<DingtalkResult>;

package/src/index.js

@@ -0,0 +1,47 @@
+/**
+ * fe-build-cli - 前端项目打包部署工具
+ *
+ * 导出所有模块供外部使用
+ */
+
+// SSH 客户端
+export { SSHClient } from './ssh-client.js';
+
+// Git 分支管理
+export {
+  getCurrentBranch,
+  getGitSha,
+  isWorkingTreeClean,
+  checkUncommittedChanges,
+  checkoutBranch,
+  pullBranch,
+  mergeBranch,
+  pushBranch,
+  executeMainBranchFlow,
+  executeCurrentBranchFlow,
+  restoreBranch
+} from './git-branch.js';
+
+// 部署核心逻辑
+export {
+  buildProject,
+  verifyBuildOutput,
+  compressBuild,
+  backupExistingDeployment,
+  uploadBuild,
+  deployAndExtract,
+  cleanupFiles,
+  deployToServer,
+  rollbackDeployment
+} from './deploy-core.js';
+
+// 钉钉通知
+export {
+  sendDingTalkMessage,
+  sendDeploySuccessNotification,
+  sendDeployFailureNotification,
+  sendRollbackNotification
+} from './dingtalk.js';
+
+// 配置模板
+export { default as configTemplate } from './config-template.js';