@gong-ym/ai-spec-auto 0.2.3

package/src/asset/asset-version.js

@@ -0,0 +1,293 @@
+/**
+ * AssetVersion — 资产版本模型
+ *
+ * 管理资产版本快照的创建、查询、比较和递增，
+ * 支持 NDJSON 文件持久化。
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ============================================================
+// semver 工具函数
+// ============================================================
+
+const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)$/;
+
+/**
+ * 解析 semver 字符串
+ * @param {string} version
+ * @returns {{ major: number, minor: number, patch: number }}
+ */
+function parseSemver(version) {
+  const match = SEMVER_RE.exec(version);
+  if (!match) {
+    throw new Error(`无效的 semver 格式: ${version}，期望 x.y.z`);
+  }
+  return {
+    major: parseInt(match[1], 10),
+    minor: parseInt(match[2], 10),
+    patch: parseInt(match[3], 10),
+  };
+}
+
+/**
+ * 比较两个 semver 版本
+ * @param {string} v1
+ * @param {string} v2
+ * @returns {number} -1 / 0 / 1
+ */
+function compareSemver(v1, v2) {
+  const a = parseSemver(v1);
+  const b = parseSemver(v2);
+
+  if (a.major !== b.major) return a.major < b.major ? -1 : 1;
+  if (a.minor !== b.minor) return a.minor < b.minor ? -1 : 1;
+  if (a.patch !== b.patch) return a.patch < b.patch ? -1 : 1;
+  return 0;
+}
+
+/**
+ * 版本号递增
+ * @param {string} current - 当前版本
+ * @param {'major'|'minor'|'patch'} type
+ * @returns {string} 新版本
+ */
+function bumpVersion(current, type) {
+  const v = parseSemver(current);
+
+  if (type === 'major') return `${v.major + 1}.0.0`;
+  if (type === 'minor') return `${v.major}.${v.minor + 1}.0`;
+  if (type === 'patch') return `${v.major}.${v.minor}.${v.patch + 1}`;
+
+  throw new Error(`无效的递增类型: ${type}，期望 major/minor/patch`);
+}
+
+// ============================================================
+// AssetVersion 类
+// ============================================================
+
+class AssetVersion {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.storagePath] - NDJSON 持久化路径
+   * @param {number} [options.maxRecords] - 最大记录数
+   */
+  constructor(options = {}) {
+    /** @type {Map<string, object[]>} assetId -> version records */
+    this._versions = new Map();
+    /** @type {number} */
+    this._nextId = 1;
+    /** @type {string|null} */
+    this.storagePath = options.storagePath || null;
+    /** @type {number} */
+    this._maxRecords = options.maxRecords || 50000;
+    /** @type {object[]} */
+    this.loadErrors = [];
+
+    if (this.storagePath) {
+      this._loadFromFile();
+    }
+  }
+
+  // ============================================================
+  // NDJSON 持久化
+  // ============================================================
+
+  _loadFromFile() {
+    if (!this.storagePath) return;
+
+    try {
+      if (!fs.existsSync(this.storagePath)) return;
+    } catch {
+      return;
+    }
+
+    let content;
+    try {
+      content = fs.readFileSync(this.storagePath, 'utf-8');
+    } catch {
+      return;
+    }
+
+    if (!content || !content.trim()) return;
+
+    const lines = content.split('\n');
+    this._versions.clear();
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (!line) continue;
+
+      try {
+        const entry = JSON.parse(line);
+        if (!entry.assetId) continue;
+
+        if (!this._versions.has(entry.assetId)) {
+          this._versions.set(entry.assetId, []);
+        }
+        this._versions.get(entry.assetId).push(entry);
+
+        // 恢复 ID 编号
+        if (entry.versionId) {
+          const match = String(entry.versionId).match(/^ver-(\d+)$/);
+          if (match) {
+            const num = parseInt(match[1], 10);
+            if (num >= this._nextId) {
+              this._nextId = num + 1;
+            }
+          }
+        }
+      } catch (err) {
+        this.loadErrors.push({
+          lineNumber: i + 1,
+          line: line.substring(0, 200),
+          message: err.message || 'JSON 解析失败',
+        });
+      }
+    }
+  }
+
+  _appendToFile(entry) {
+    if (!this.storagePath) return;
+
+    const dir = path.dirname(this.storagePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    const line = JSON.stringify(entry) + '\n';
+    fs.appendFileSync(this.storagePath, line, 'utf-8');
+  }
+
+  // ============================================================
+  // create — 创建版本快照
+  // ============================================================
+
+  /**
+   * 创建版本快照
+   * @param {string} assetId
+   * @param {object} spec
+   * @returns {object} 版本记录
+   */
+  create(assetId, spec) {
+    if (!assetId || typeof assetId !== 'string') {
+      throw new Error('assetId 必须为非空字符串');
+    }
+    if (!spec || !spec.version || typeof spec.version !== 'string') {
+      throw new Error('version 必须为非空字符串');
+    }
+
+    // 校验 semver 格式
+    parseSemver(spec.version);
+
+    const record = {
+      versionId: `ver-${this._nextId++}`,
+      assetId,
+      version: spec.version,
+      changelog: spec.changelog || '',
+      checksum: spec.checksum || '',
+      fileMap: spec.fileMap || {},
+      dependencies: Array.isArray(spec.dependencies) ? [...spec.dependencies] : [],
+      createdAt: new Date().toISOString(),
+      createdBy: spec.createdBy || 'system',
+    };
+
+    if (!this._versions.has(assetId)) {
+      this._versions.set(assetId, []);
+    }
+    this._versions.get(assetId).push(record);
+
+    this._appendToFile(record);
+
+    return { ...record, fileMap: { ...record.fileMap }, dependencies: [...record.dependencies] };
+  }
+
+  // ============================================================
+  // get — 获取指定版本
+  // ============================================================
+
+  /**
+   * 获取指定版本
+   * @param {string} assetId
+   * @param {string} version
+   * @returns {object|null}
+   */
+  get(assetId, version) {
+    const list = this._versions.get(assetId);
+    if (!list) return null;
+
+    const record = list.find(r => r.version === version);
+    if (!record) return null;
+
+    return { ...record, fileMap: { ...record.fileMap }, dependencies: [...record.dependencies] };
+  }
+
+  // ============================================================
+  // list — 列出所有版本
+  // ============================================================
+
+  /**
+   * 列出资产的所有版本
+   * @param {string} assetId
+   * @returns {object[]}
+   */
+  list(assetId) {
+    const list = this._versions.get(assetId);
+    if (!list) return [];
+
+    return list.map(r => ({ ...r, fileMap: { ...r.fileMap }, dependencies: [...r.dependencies] }));
+  }
+
+  // ============================================================
+  // latest — 获取最新版本
+  // ============================================================
+
+  /**
+   * 获取最新版本（按 semver 排序）
+   * @param {string} assetId
+   * @returns {object|null}
+   */
+  latest(assetId) {
+    const list = this._versions.get(assetId);
+    if (!list || list.length === 0) return null;
+
+    let max = list[0];
+    for (let i = 1; i < list.length; i++) {
+      if (compareSemver(list[i].version, max.version) > 0) {
+        max = list[i];
+      }
+    }
+
+    return { ...max, fileMap: { ...max.fileMap }, dependencies: [...max.dependencies] };
+  }
+
+  // ============================================================
+  // getLoadErrors
+  // ============================================================
+
+  /** @returns {object[]} */
+  getLoadErrors() {
+    return this.loadErrors.map(e => ({ ...e }));
+  }
+}
+
+// ============================================================
+// 工厂函数
+// ============================================================
+
+/**
+ * 创建资产版本管理器
+ * @param {object} [options]
+ * @returns {AssetVersion}
+ */
+function createAssetVersion(options) {
+  return new AssetVersion(options);
+}
+
+module.exports = {
+  createAssetVersion,
+  AssetVersion,
+  compareSemver,
+  bumpVersion,
+};

package/src/asset/index.js

@@ -0,0 +1,86 @@
+const {
+  ASSET_PACKAGE_VERSION,
+  ASSET_TYPES,
+  ASSET_SOURCES,
+  VALID_ASSET_TYPES,
+  VALID_ASSET_SOURCES,
+  createAssetPackage,
+  validateAssetPackage,
+  computeAssetChecksum,
+  guessAssetType,
+  buildAssetIdentity,
+} = require('./asset-package');
+
+const { AssetPackageManager } = require('./asset-package-manager');
+
+const { AssetRegistry, createAssetRegistry, ASSET_REGISTRY_STATUSES, VALID_REGISTRY_STATUSES } = require('./asset-registry');
+const { AssetVersion, createAssetVersion, compareSemver, bumpVersion } = require('./asset-version');
+const { AssetDependency, createAssetDependency } = require('./asset-dependency');
+const { AssetInstall, createAssetInstall, INSTALL_STATUSES, VALID_INSTALL_STATUSES } = require('./asset-install');
+const { AssetFeedback, createAssetFeedback, FEEDBACK_CATEGORIES, VALID_FEEDBACK_CATEGORIES, FEEDBACK_STATUSES, VALID_FEEDBACK_STATUSES } = require('./asset-feedback');
+
+const { AssetManager, createAssetManager } = require('./asset-manager');
+
+const { AssetInstaller, createAssetInstaller } = require('./asset-installer');
+
+const { AssetLifecycle, createAssetLifecycle } = require('./asset-lifecycle');
+
+const { AssetFork, createAssetFork } = require('./asset-fork');
+
+const { AssetQuality, createAssetQuality } = require('./asset-quality');
+
+module.exports = {
+  // asset-package schema
+  ASSET_PACKAGE_VERSION,
+  ASSET_TYPES,
+  ASSET_SOURCES,
+  VALID_ASSET_TYPES,
+  VALID_ASSET_SOURCES,
+  createAssetPackage,
+  validateAssetPackage,
+  computeAssetChecksum,
+  guessAssetType,
+  buildAssetIdentity,
+  // asset-package-manager
+  AssetPackageManager,
+  // P5.1 — asset-registry
+  AssetRegistry,
+  createAssetRegistry,
+  ASSET_REGISTRY_STATUSES,
+  VALID_REGISTRY_STATUSES,
+  // P5.1 — asset-version
+  AssetVersion,
+  createAssetVersion,
+  compareSemver,
+  bumpVersion,
+  // P5.1 — asset-dependency
+  AssetDependency,
+  createAssetDependency,
+  // P5.1 — asset-install
+  AssetInstall,
+  createAssetInstall,
+  INSTALL_STATUSES,
+  VALID_INSTALL_STATUSES,
+  // P5.1 — asset-feedback
+  AssetFeedback,
+  createAssetFeedback,
+  FEEDBACK_CATEGORIES,
+  VALID_FEEDBACK_CATEGORIES,
+  FEEDBACK_STATUSES,
+  VALID_FEEDBACK_STATUSES,
+  // P5.2 — asset-manager
+  AssetManager,
+  createAssetManager,
+  // P5.3 — asset-installer
+  AssetInstaller,
+  createAssetInstaller,
+  // P5.4 — asset-lifecycle
+  AssetLifecycle,
+  createAssetLifecycle,
+  // P5.5 — asset-fork
+  AssetFork,
+  createAssetFork,
+  // P5.6 — asset-quality
+  AssetQuality,
+  createAssetQuality,
+};

package/src/cache/agent-profile-cache.js

@@ -0,0 +1,59 @@
+const fs = require('fs');
+const path = require('path');
+const { GlobalCache } = require('./global-cache');
+const { safeJsonHash } = require('../security/checksum');
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+class AgentProfileCache {
+  constructor(options = {}) {
+    this.globalCache = options.globalCache || new GlobalCache(options);
+  }
+
+  hasValidProfile(profile) {
+    const contentPath = this.globalCache.getAgentProfileContentPath(profile.checksum);
+    if (!fs.existsSync(contentPath)) return false;
+    const parsed = JSON.parse(fs.readFileSync(contentPath, 'utf8'));
+    return safeJsonHash(parsed) === profile.checksum;
+  }
+
+  writeProfile(profile, profileExport) {
+    const content = profileExport.content || profileExport;
+    const actual = safeJsonHash(content);
+    if (actual !== profile.checksum) {
+      throw new Error(`Agent Profile checksum 不一致：${profile.slug || profile.checksum}，期望 ${profile.checksum}，实际 ${actual}`);
+    }
+    const dir = this.globalCache.getAgentProfileDir(profile.checksum);
+    fs.mkdirSync(dir, { recursive: true });
+    writeJson(this.globalCache.getAgentProfileContentPath(profile.checksum), content);
+    writeJson(this.globalCache.getAgentProfileMetadataPath(profile.checksum), {
+      slug: profile.slug || profileExport.slug || '',
+      version: profile.version || profileExport.version || '',
+      checksum: profile.checksum,
+      source: 'hub',
+      cachedAt: new Date().toISOString(),
+    });
+    return {
+      checksum: profile.checksum,
+      contentPath: this.globalCache.getAgentProfileContentPath(profile.checksum),
+    };
+  }
+
+  read(slug, version) {
+    const legacyPath = path.join(this.globalCache.agentProfilesDir, `${slug}@${version || 'latest'}.json`);
+    if (!fs.existsSync(legacyPath)) return null;
+    return JSON.parse(fs.readFileSync(legacyPath, 'utf8'));
+  }
+
+  write(slug, version, profileExport) {
+    const checksum = profileExport.checksum || safeJsonHash(profileExport.content || profileExport);
+    return this.writeProfile({ slug, version, checksum }, profileExport).contentPath;
+  }
+}
+
+module.exports = {
+  AgentProfileCache,
+};

package/src/cache/asset-cache.js

@@ -0,0 +1,63 @@
+const fs = require('fs');
+const path = require('path');
+const { sha256File, sha256Text } = require('../security/checksum');
+const { GlobalCache } = require('./global-cache');
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function readJsonIfExists(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+class AssetCache {
+  constructor(options = {}) {
+    this.globalCache = options.globalCache || new GlobalCache(options);
+  }
+
+  hasValidAsset(asset) {
+    const contentPath = this.globalCache.getAssetContentPath(asset.checksum);
+    if (!fs.existsSync(contentPath)) return false;
+    return sha256File(contentPath) === asset.checksum;
+  }
+
+  getCachedAsset(asset) {
+    if (!this.hasValidAsset(asset)) return null;
+    return {
+      checksum: asset.checksum,
+      contentPath: this.globalCache.getAssetContentPath(asset.checksum),
+      metadata: readJsonIfExists(this.globalCache.getAssetMetadataPath(asset.checksum)),
+    };
+  }
+
+  writeAsset(asset, content) {
+    const actual = sha256Text(content);
+    if (actual !== asset.checksum) {
+      throw new Error(`资产 checksum 不一致：${asset.slug || asset.checksum}，期望 ${asset.checksum}，实际 ${actual}`);
+    }
+    const assetDir = this.globalCache.getAssetDir(asset.checksum);
+    fs.mkdirSync(assetDir, { recursive: true });
+    fs.writeFileSync(this.globalCache.getAssetContentPath(asset.checksum), content, 'utf8');
+    writeJson(this.globalCache.getAssetMetadataPath(asset.checksum), {
+      kind: asset.kind || 'asset',
+      slug: asset.slug || '',
+      version: asset.version || '',
+      checksum: asset.checksum,
+      cacheKey: asset.checksum,
+      cachePath: this.globalCache.getRelativeAssetPath(asset.checksum),
+      cachedAt: new Date().toISOString(),
+    });
+    return this.getCachedAsset(asset);
+  }
+}
+
+module.exports = {
+  AssetCache,
+};

package/src/cache/global-cache.js

@@ -0,0 +1,61 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function resolveGlobalCacheRoot(options = {}) {
+  return path.resolve(options.rootDir || process.env.AI_SPEC_AUTO_HOME || path.join(os.homedir(), '.ai-spec-auto'));
+}
+
+class GlobalCache {
+  constructor(options = {}) {
+    this.rootDir = resolveGlobalCacheRoot(options);
+    this.cacheDir = path.join(this.rootDir, 'cache');
+    this.assetsDir = path.join(this.cacheDir, 'assets');
+    this.manifestsDir = path.join(this.cacheDir, 'manifests');
+    this.agentProfilesDir = path.join(this.cacheDir, 'agent-profiles');
+    this.logsDir = path.join(this.rootDir, 'logs');
+  }
+
+  ensureLayout() {
+    for (const dirPath of [this.assetsDir, this.manifestsDir, this.agentProfilesDir, this.logsDir]) {
+      fs.mkdirSync(dirPath, { recursive: true });
+    }
+  }
+
+  getAssetDir(checksum) {
+    return path.join(this.assetsDir, checksum);
+  }
+
+  getAssetContentPath(checksum) {
+    return path.join(this.getAssetDir(checksum), 'content.md');
+  }
+
+  getAssetMetadataPath(checksum) {
+    return path.join(this.getAssetDir(checksum), 'metadata.json');
+  }
+
+  getRelativeAssetPath(checksum) {
+    return `assets/${checksum}`;
+  }
+
+  getAgentProfileDir(checksum) {
+    return path.join(this.agentProfilesDir, checksum);
+  }
+
+  getAgentProfileContentPath(checksum) {
+    return path.join(this.getAgentProfileDir(checksum), 'content.json');
+  }
+
+  getAgentProfileMetadataPath(checksum) {
+    return path.join(this.getAgentProfileDir(checksum), 'metadata.json');
+  }
+
+  getRelativeAgentProfilePath(checksum) {
+    return `agent-profiles/${checksum}`;
+  }
+}
+
+module.exports = {
+  GlobalCache,
+  resolveGlobalCacheRoot,
+};

package/src/cache/manifest-cache.js

@@ -0,0 +1,30 @@
+const fs = require('fs');
+const path = require('path');
+const { GlobalCache } = require('./global-cache');
+
+class ManifestCache {
+  constructor(options = {}) {
+    this.globalCache = options.globalCache || new GlobalCache(options);
+  }
+
+  getManifestPath(slug, version) {
+    return path.join(this.globalCache.manifestsDir, `${slug}@${version || 'latest'}.json`);
+  }
+
+  read(slug, version) {
+    const filePath = this.getManifestPath(slug, version);
+    if (!fs.existsSync(filePath)) return null;
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  }
+
+  write(slug, version, manifestExport) {
+    const filePath = this.getManifestPath(slug, version);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, `${JSON.stringify(manifestExport, null, 2)}\n`, 'utf8');
+    return filePath;
+  }
+}
+
+module.exports = {
+  ManifestCache,
+};

package/src/check/check-service.js

@@ -0,0 +1,32 @@
+const { GlobalCache } = require('../cache/global-cache');
+const { AssetTamperChecker } = require('../security/asset-tamper-checker');
+
+function summarize(result) {
+  return {
+    errors: result.errors.length,
+    warnings: result.warnings.length,
+    infos: result.infos.length,
+  };
+}
+
+class CheckService {
+  constructor(options = {}) {
+    this.globalCache = options.globalCache || new GlobalCache(options);
+    this.tamperChecker = options.tamperChecker || new AssetTamperChecker({ globalCache: this.globalCache });
+  }
+
+  check(rootDir, options = {}) {
+    const result = this.tamperChecker.check(rootDir, {
+      strictCache: Boolean(options.strictCache),
+    });
+    return {
+      ...result,
+      summary: summarize(result),
+    };
+  }
+}
+
+module.exports = {
+  CheckService,
+  summarize,
+};