@gong-ym/ai-spec-auto 0.2.3

package/src/asset/asset-package-manager.js

@@ -0,0 +1,349 @@
+/**
+ * AssetPackageManager — 资产包生命周期管理
+ *
+ * 统一管理资产包的安装、升级、回滚、checksum 校验和 generatedFiles 追踪。
+ * 在现有 local-init 和 hub-install 之上提供标准化抽象层。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { createChecksum, readJsonIfExists, writeJson, ensureDir, toPosixPath } = require('../project/json-utils');
+const {
+  ASSET_TYPES,
+  ASSET_SOURCES,
+  createAssetPackage,
+  validateAssetPackage,
+  computeAssetChecksum,
+  guessAssetType,
+  buildAssetIdentity,
+} = require('./asset-package');
+
+// ============================================================
+// 包级 checksum 计算
+// ============================================================
+
+/**
+ * 基于 generatedFiles 计算包级 checksum
+ * 规则：对文件排序后，拼接 "相对路径 + 分隔符 + 文件内容"，整体计算 sha256
+ * 使用 posix 路径分隔符保证跨平台一致性
+ * @param {string} rootDir
+ * @param {string[]} generatedFiles
+ * @returns {string}
+ */
+function computePackageChecksumFromFiles(rootDir, generatedFiles) {
+  const sorted = [...generatedFiles].sort();
+  const parts = [];
+  for (const filePath of sorted) {
+    const posixPath = toPosixPath(filePath);
+    const fullPath = path.join(rootDir, filePath);
+    const content = fs.readFileSync(fullPath, 'utf8');
+    parts.push(`${posixPath}\n---AI_SPEC_FILE_CONTENT---\n${content}`);
+  }
+  return createChecksum(parts.join('\n'));
+}
+
+// ============================================================
+// AssetPackageManager
+// ============================================================
+
+class AssetPackageManager {
+  /**
+   * @param {string} rootDir - 项目根目录
+   * @param {Object} [options]
+   * @param {string} [options.backupDir] - 备份目录，默认 .ai-spec/backups
+   */
+  constructor(rootDir, options = {}) {
+    this.rootDir = rootDir;
+    this.backupDir = options.backupDir || path.join(rootDir, '.ai-spec/backups');
+  }
+
+  // ============================================================
+  // install — 安装资产包
+  // ============================================================
+
+  /**
+   * 安装资产包到项目
+   * @param {AssetPackage} pkg - 资产包
+   * @param {Object} fileMap - { relativePath: content } 的文件映射
+   * @returns {{ ok: boolean, installedFiles: string[], errors: string[] }}
+   */
+  install(pkg, fileMap = {}) {
+    const errors = [];
+
+    // 校验资产包
+    const validation = validateAssetPackage(pkg);
+    if (!validation.ok) {
+      return { ok: false, installedFiles: [], errors: validation.errors };
+    }
+
+    const installedFiles = [];
+
+    try {
+      for (const [relativePath, content] of Object.entries(fileMap)) {
+        const fullPath = path.join(this.rootDir, relativePath);
+        ensureDir(path.dirname(fullPath));
+        fs.writeFileSync(fullPath, content, 'utf8');
+        installedFiles.push(relativePath);
+      }
+
+      return { ok: true, installedFiles, errors: [] };
+    } catch (error) {
+      // 安装失败时回滚已写入文件
+      for (const filePath of installedFiles) {
+        try {
+          const fullPath = path.join(this.rootDir, filePath);
+          if (fs.existsSync(fullPath)) {
+            fs.unlinkSync(fullPath);
+          }
+        } catch {
+          // 回滚失败记录但不阻断
+          errors.push(`回滚失败: ${filePath}`);
+        }
+      }
+      errors.push(`安装失败: ${error.message}`);
+      return { ok: false, installedFiles: [], errors };
+    }
+  }
+
+  // ============================================================
+  // upgrade — 升级资产包
+  // ============================================================
+
+  /**
+   * 升级资产包：备份旧版本、写入新版本
+   * @param {AssetPackage} oldPkg - 旧资产包
+   * @param {AssetPackage} newPkg - 新资产包
+   * @param {Object} newFileMap - 新版本的文件映射
+   * @returns {{ ok: boolean, upgradedFiles: string[], backupId: string, errors: string[] }}
+   */
+  upgrade(oldPkg, newPkg, newFileMap = {}) {
+    const errors = [];
+
+    // 校验新资产包
+    const validation = validateAssetPackage(newPkg);
+    if (!validation.ok) {
+      return { ok: false, upgradedFiles: [], backupId: '', errors: validation.errors };
+    }
+
+    // 备份旧文件
+    const backupId = `${oldPkg.assetId}@${oldPkg.version}-${Date.now()}`;
+    const backupPath = path.join(this.backupDir, backupId);
+
+    try {
+      ensureDir(backupPath);
+
+      // 备份旧资产生成的文件
+      for (const filePath of oldPkg.generatedFiles) {
+        const fullPath = path.join(this.rootDir, filePath);
+        if (fs.existsSync(fullPath)) {
+          const backupFilePath = path.join(backupPath, filePath);
+          ensureDir(path.dirname(backupFilePath));
+          fs.copyFileSync(fullPath, backupFilePath);
+        }
+      }
+
+      // 保存旧资产包元数据
+      writeJson(path.join(backupPath, '.asset-package.json'), oldPkg);
+
+      // 安装新版本
+      const installResult = this.install(newPkg, newFileMap);
+      if (!installResult.ok) {
+        return { ok: false, upgradedFiles: [], backupId, errors: installResult.errors };
+      }
+
+      return { ok: true, upgradedFiles: installResult.installedFiles, backupId, errors: [] };
+    } catch (error) {
+      errors.push(`升级失败: ${error.message}`);
+      return { ok: false, upgradedFiles: [], backupId, errors };
+    }
+  }
+
+  // ============================================================
+  // rollback — 回滚资产包
+  // ============================================================
+
+  /**
+   * 回滚资产包到指定备份
+   * @param {string} backupId - 备份 ID
+   * @param {AssetPackage} currentPkg - 当前资产包
+   * @returns {{ ok: boolean, restoredFiles: string[], deletedFiles: string[], errors: string[] }}
+   */
+  rollback(backupId, currentPkg) {
+    const backupPath = path.join(this.backupDir, backupId);
+    const errors = [];
+    const restoredFiles = [];
+    const deletedFiles = [];
+
+    if (!fs.existsSync(backupPath)) {
+      return { ok: false, restoredFiles, deletedFiles, errors: [`备份不存在: ${backupId}`] };
+    }
+
+    try {
+      // 读取备份的资产包元数据
+      const backupPkg = readJsonIfExists(path.join(backupPath, '.asset-package.json'));
+
+      // 删除当前版本新增的文件（备份中不存在的）
+      for (const filePath of currentPkg.generatedFiles) {
+        const backupFilePath = path.join(backupPath, filePath);
+        if (!fs.existsSync(backupFilePath)) {
+          const fullPath = path.join(this.rootDir, filePath);
+          if (fs.existsSync(fullPath)) {
+            fs.unlinkSync(fullPath);
+            deletedFiles.push(filePath);
+          }
+        }
+      }
+
+      // 恢复备份中的文件
+      const filesToRestore = backupPkg ? backupPkg.generatedFiles : [];
+      for (const filePath of filesToRestore) {
+        const backupFilePath = path.join(backupPath, filePath);
+        if (fs.existsSync(backupFilePath)) {
+          const fullPath = path.join(this.rootDir, filePath);
+          ensureDir(path.dirname(fullPath));
+          fs.copyFileSync(backupFilePath, fullPath);
+          restoredFiles.push(filePath);
+        }
+      }
+
+      return { ok: true, restoredFiles, deletedFiles, errors: [] };
+    } catch (error) {
+      errors.push(`回滚失败: ${error.message}`);
+      return { ok: false, restoredFiles, deletedFiles, errors };
+    }
+  }
+
+  // ============================================================
+  // verifyChecksum — checksum 校验
+  // ============================================================
+
+  /**
+   * 校验资产包的 checksum 是否与文件内容一致
+   * @param {AssetPackage} pkg
+   * @returns {{ ok: boolean, expected: string, actual: string, errors: string[] }}
+   */
+  verifyChecksum(pkg) {
+    const errors = [];
+
+    if (!pkg.generatedFiles || pkg.generatedFiles.length === 0) {
+      return { ok: true, expected: pkg.checksum || '', actual: pkg.checksum || '', errors };
+    }
+
+    // 检查所有文件是否存在
+    for (const filePath of pkg.generatedFiles) {
+      const fullPath = path.join(this.rootDir, filePath);
+      if (!fs.existsSync(fullPath)) {
+        errors.push(`文件不存在: ${filePath}`);
+      }
+    }
+
+    if (errors.length > 0) {
+      return { ok: false, expected: pkg.checksum, actual: '', errors };
+    }
+
+    // 计算包级 checksum 并与 pkg.checksum 比较
+    const actual = computePackageChecksumFromFiles(this.rootDir, pkg.generatedFiles);
+    const ok = actual === pkg.checksum;
+
+    return { ok, expected: pkg.checksum, actual, errors };
+  }
+
+  /**
+   * 校验单个文件的 checksum
+   * @param {string} relativePath
+   * @param {string} expectedChecksum
+   * @returns {{ ok: boolean, actual: string }}
+   */
+  verifyFileChecksum(relativePath, expectedChecksum) {
+    const fullPath = path.join(this.rootDir, relativePath);
+    if (!fs.existsSync(fullPath)) {
+      return { ok: false, actual: '' };
+    }
+
+    const content = fs.readFileSync(fullPath, 'utf8');
+    const actual = computeAssetChecksum(content);
+    return { ok: actual === expectedChecksum, actual };
+  }
+
+  // ============================================================
+  // generatedFiles — 清单追踪
+  // ============================================================
+
+  /**
+   * 获取资产包生成的文件列表
+   * @param {AssetPackage} pkg
+   * @returns {Array<{ path: string, exists: boolean }>}
+   */
+  getGeneratedFiles(pkg) {
+    if (!pkg.generatedFiles || !Array.isArray(pkg.generatedFiles)) {
+      return [];
+    }
+
+    return pkg.generatedFiles.map((filePath) => ({
+      path: filePath,
+      exists: fs.existsSync(path.join(this.rootDir, filePath)),
+    }));
+  }
+
+  /**
+   * 清理资产包生成的所有文件
+   * @param {AssetPackage} pkg
+   * @returns {{ deletedFiles: string[], errors: string[] }}
+   */
+  cleanupGeneratedFiles(pkg) {
+    const deletedFiles = [];
+    const errors = [];
+
+    if (!pkg.generatedFiles || !Array.isArray(pkg.generatedFiles)) {
+      return { deletedFiles, errors };
+    }
+
+    for (const filePath of pkg.generatedFiles) {
+      const fullPath = path.join(this.rootDir, filePath);
+      try {
+        if (fs.existsSync(fullPath)) {
+          fs.unlinkSync(fullPath);
+          deletedFiles.push(filePath);
+        }
+      } catch (error) {
+        errors.push(`删除失败: ${filePath} - ${error.message}`);
+      }
+    }
+
+    return { deletedFiles, errors };
+  }
+
+  // ============================================================
+  // listBackups — 列出备份
+  // ============================================================
+
+  /**
+   * 列出指定资产的所有备份
+   * @param {string} assetId
+   * @returns {Array<{ backupId: string, backupPath: string, pkg: AssetPackage|null }>}
+   */
+  listBackups(assetId) {
+    if (!fs.existsSync(this.backupDir)) {
+      return [];
+    }
+
+    const backups = [];
+    const entries = fs.readdirSync(this.backupDir);
+
+    for (const entry of entries) {
+      if (!entry.startsWith(assetId)) continue;
+      const backupPath = path.join(this.backupDir, entry);
+      if (!fs.statSync(backupPath).isDirectory()) continue;
+
+      const pkg = readJsonIfExists(path.join(backupPath, '.asset-package.json'));
+      backups.push({ backupId: entry, backupPath, pkg });
+    }
+
+    return backups;
+  }
+}
+
+module.exports = {
+  AssetPackageManager,
+  computePackageChecksumFromFiles,
+};

package/src/asset/asset-package.js

@@ -0,0 +1,186 @@
+/**
+ * AssetPackage — 资产包 schema 定义与校验
+ *
+ * 统一资产包的类型、身份标识和校验规则，
+ * 解决 local-init 与 hub-install 两套系统资产形状不一致的问题。
+ */
+
+const { createChecksum } = require('../project/json-utils');
+
+// ============================================================
+// 常量
+// ============================================================
+
+const ASSET_PACKAGE_VERSION = '1.0.0';
+
+/** 资产类型枚举 */
+const ASSET_TYPES = Object.freeze({
+  RULE: 'rule',
+  SKILL: 'skill',
+  AGENT_PROFILE: 'agentProfile',
+  COMMAND: 'command',
+  HOOK: 'hook',
+  MEMORY: 'memory',
+  CONFIG: 'config',
+  ADAPTER: 'adapter',
+  OTHER: 'other',
+});
+
+/** 资产来源枚举 */
+const ASSET_SOURCES = Object.freeze({
+  LOCAL: 'local',
+  HUB: 'hub',
+  TEMPLATE: 'template',
+});
+
+/** 所有合法资产类型值 */
+const VALID_ASSET_TYPES = new Set(Object.values(ASSET_TYPES));
+
+/** 所有合法来源值 */
+const VALID_ASSET_SOURCES = new Set(Object.values(ASSET_SOURCES));
+
+// ============================================================
+// createAssetPackage — 工厂函数
+// ============================================================
+
+/**
+ * 构建标准化的 AssetPackage 对象
+ * @param {Object} overrides - 覆盖字段
+ * @returns {AssetPackage}
+ */
+function createAssetPackage(overrides = {}) {
+  const now = new Date().toISOString();
+  return {
+    assetId: '',
+    assetType: ASSET_TYPES.OTHER,
+    version: '0.1.0',
+    source: ASSET_SOURCES.LOCAL,
+    checksum: '',
+    lockedAt: now,
+    generatedFiles: [],
+    ...overrides,
+  };
+}
+
+// ============================================================
+// validateAssetPackage — 校验函数
+// ============================================================
+
+/**
+ * 校验 AssetPackage 是否合法
+ * @param {AssetPackage} pkg
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+function validateAssetPackage(pkg) {
+  const errors = [];
+
+  if (!pkg || typeof pkg !== 'object') {
+    return { ok: false, errors: ['asset package 必须是对象'] };
+  }
+
+  if (!pkg.assetId || typeof pkg.assetId !== 'string') {
+    errors.push('assetId 必须为非空字符串');
+  }
+
+  if (!VALID_ASSET_TYPES.has(pkg.assetType)) {
+    errors.push(`assetType 必须为 ${[...VALID_ASSET_TYPES].join('/')} 之一，当前值: ${pkg.assetType}`);
+  }
+
+  if (!pkg.version || typeof pkg.version !== 'string') {
+    errors.push('version 必须为非空字符串');
+  }
+
+  if (!VALID_ASSET_SOURCES.has(pkg.source)) {
+    errors.push(`source 必须为 ${[...VALID_ASSET_SOURCES].join('/')} 之一，当前值: ${pkg.source}`);
+  }
+
+  if (!pkg.checksum || typeof pkg.checksum !== 'string') {
+    errors.push('checksum 必须为非空字符串');
+  }
+
+  if (!Array.isArray(pkg.generatedFiles)) {
+    errors.push('generatedFiles 必须为数组');
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+  };
+}
+
+// ============================================================
+// computeAssetChecksum — 基于内容计算 checksum
+// ============================================================
+
+/**
+ * 根据资产内容计算 checksum
+ * @param {string} content - 资产文件内容
+ * @returns {string}
+ */
+function computeAssetChecksum(content) {
+  return createChecksum(content);
+}
+
+// ============================================================
+// guessAssetType — 从路径推断资产类型
+// ============================================================
+
+/**
+ * 根据文件路径推断资产类型
+ * @param {string} filePath
+ * @returns {string}
+ */
+function guessAssetType(filePath) {
+  if (filePath.startsWith('.agents/rules/')) return ASSET_TYPES.RULE;
+  if (filePath.startsWith('.agents/skills/')) return ASSET_TYPES.SKILL;
+  if (filePath.startsWith('.agents/roles/') || filePath.startsWith('.agents/profiles/')) return ASSET_TYPES.AGENT_PROFILE;
+  if (filePath.startsWith('.agents/commands/')) return ASSET_TYPES.COMMAND;
+  if (filePath.startsWith('.harness/')) return ASSET_TYPES.HOOK;
+  if (filePath.startsWith('.memory/')) return ASSET_TYPES.MEMORY;
+  if (filePath.startsWith('.ai-spec/')) return ASSET_TYPES.CONFIG;
+  if (filePath.startsWith('.cursor/') || filePath.startsWith('.claude/') || filePath.startsWith('.codex/')) return ASSET_TYPES.ADAPTER;
+  return ASSET_TYPES.OTHER;
+}
+
+// ============================================================
+// buildAssetIdentity — 标准化资产身份标识
+// ============================================================
+
+/**
+ * 构建资产唯一身份标识
+ * @param {string} assetType
+ * @param {string} assetId
+ * @param {string} version
+ * @returns {string} 格式: type:id@version
+ */
+function buildAssetIdentity(assetType, assetId, version) {
+  return `${assetType}:${assetId}@${version}`;
+}
+
+// ============================================================
+// 类型定义 (JSDoc)
+// ============================================================
+
+/**
+ * @typedef {Object} AssetPackage
+ * @property {string} assetId - 资产唯一标识
+ * @property {string} assetType - 资产类型 (rule/skill/agentProfile/command/hook/memory/config/adapter/other)
+ * @property {string} version - 资产版本
+ * @property {string} source - 资产来源 (local/hub/template)
+ * @property {string} checksum - 资产内容摘要
+ * @property {string} lockedAt - 锁定时间 ISO 格式
+ * @property {string[]} generatedFiles - 生成的文件列表
+ */
+
+module.exports = {
+  ASSET_PACKAGE_VERSION,
+  ASSET_TYPES,
+  ASSET_SOURCES,
+  VALID_ASSET_TYPES,
+  VALID_ASSET_SOURCES,
+  createAssetPackage,
+  validateAssetPackage,
+  computeAssetChecksum,
+  guessAssetType,
+  buildAssetIdentity,
+};