@liangjie559567/ultrapower 5.5.25 → 5.5.26

package/.claude-plugin/marketplace.json

@@ -8,11 +8,11 @@
     {
       "name": "ultrapower",
       "description": "Disciplined multi-agent orchestration: workflow enforcement + parallel execution",
-      "version": "5.5.25",
+      "version": "5.5.26",
       "source": {
         "source": "npm",
         "package": "@liangjie559567/ultrapower",
-        "version": "5.5.25"
+        "version": "5.5.26"
       },
       "author": {
         "name": "liangjie559567"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ultrapower",
   "description": "Disciplined multi-agent orchestration: workflow enforcement + parallel execution",
-  "version": "5.5.25",
+  "version": "5.5.26",
   "author": {
     "name": "liangjie559567"
   },

package/docs/standards/release-process.md

@@ -0,0 +1,85 @@
+# Release Process
+
+## 版本同步检查清单
+
+发布前必须确保以下文件版本一致：
+
+1. `package.json` - npm 包版本
+2. `.claude-plugin/plugin.json` - 用户看到的插件版本
+3. `.claude-plugin/marketplace.json` - 插件市场版本
+
+## 自动化验证
+
+### 本地验证
+
+```bash
+npm run validate:versions
+```
+
+### CI 验证
+
+版本验证已集成到 GitHub Actions release 工作流的 preflight 步骤中。
+
+## 发布流程
+
+### 标准发布（推荐）
+
+1. 更新版本号：
+   ```bash
+   npm run bump -- 5.5.26
+   ```
+
+2. 验证版本同步：
+   ```bash
+   npm run validate:versions
+   ```
+
+3. 提交并打标签：
+   ```bash
+   git add -A
+   git commit -m "chore: bump version to 5.5.26"
+   git tag v5.5.26
+   git push origin main
+   git push origin v5.5.26
+   ```
+
+4. GitHub Actions 自动执行：
+   - 构建和测试
+   - 发布到 npm
+   - 创建 GitHub Release
+   - 同步 marketplace.json 和 plugin.json
+
+### 手动发布（仅用于调试）
+
+```bash
+npm run release:dry-run  # 预览
+npm run release:local    # 执行
+```
+
+## 故障排查
+
+### 版本不一致
+
+如果 `validate:versions` 失败：
+
+```bash
+# 查看差异
+git diff package.json .claude-plugin/plugin.json .claude-plugin/marketplace.json
+
+# 手动修复后重新验证
+npm run validate:versions
+```
+
+### CI 失败
+
+1. 检查 GitHub Actions 日志
+2. 本地重现问题：
+   ```bash
+   npm run test:run
+   npm run build
+   ```
+
+## 相关知识
+
+- [k-077: Multi-File Version Sync in Release Pipeline](../../.omc/axiom/evolution/knowledge_base.md#k-077)
+- [k-074: Version Number Sync Checklist](../../.omc/axiom/evolution/knowledge_base.md#k-074)

package/docs/standards/testing-guide.md

@@ -0,0 +1,94 @@
+# Testing Guide
+
+## 测试环境隔离模式
+
+### 标准模式（推荐）
+
+所有需要文件系统操作或 git 环境的测试必须使用隔离的测试目录：
+
+```typescript
+import { join } from 'path';
+import { homedir } from 'os';
+import { mkdirSync, rmSync, existsSync } from 'fs';
+
+describe('test suite', () => {
+  const testDir = join(homedir(), '.omc', 'test-unique-name');
+
+  beforeEach(() => {
+    mkdirSync(testDir, { recursive: true });
+    try {
+      require('child_process').execSync('git init', { cwd: testDir, stdio: 'ignore' });
+    } catch (e) {
+      // Ignore if git init fails
+    }
+  });
+
+  afterEach(() => {
+    if (existsSync(testDir)) {
+      rmSync(testDir, { recursive: true, force: true });
+    }
+  });
+
+  it('should use testDir instead of process.cwd()', () => {
+    const config = {
+      workingDirectory: testDir  // ✅ 正确
+      // workingDirectory: process.cwd()  // ❌ 错误
+    };
+  });
+});
+```
+
+### 关键要素
+
+1. **使用 `homedir()`**：确保路径在用户目录下
+2. **唯一测试目录名**：避免并发测试冲突
+3. **`beforeEach` 中初始化 git**：满足 worktree 检查
+4. **`afterEach` 中清理**：避免测试污染
+5. **使用 `testDir` 而非 `process.cwd()`**：CI 环境兼容
+
+### 反模式
+
+❌ **错误**：使用 `process.cwd()`
+```typescript
+const config = {
+  workingDirectory: process.cwd()  // CI 中路径不可控
+};
+```
+
+✅ **正确**：使用隔离的 `testDir`
+```typescript
+const testDir = join(homedir(), '.omc', 'test-my-feature');
+const config = {
+  workingDirectory: testDir
+};
+```
+
+## 跨平台注意事项
+
+### Windows vs Linux
+
+- **路径分隔符**：使用 `path.join()` 而非手动拼接
+- **`process.cwd()` 行为**：
+  - Linux CI: `/home/runner/work/repo/repo`
+  - Windows CI: `D:/a/repo/repo`
+  - 两者都可能在 home 目录外部
+
+### Git 环境
+
+测试目录默认不是 git 仓库，需要显式初始化：
+
+```typescript
+beforeEach(() => {
+  mkdirSync(testDir, { recursive: true });
+  try {
+    execSync('git init', { cwd: testDir, stdio: 'ignore' });
+  } catch (e) {
+    // Ignore if git not available
+  }
+});
+```
+
+## 相关知识
+
+- [k-078: CI Test Environment Isolation Pattern](../../.omc/axiom/evolution/knowledge_base.md#k-078)
+- [k-079: Batch Fix Same-Pattern Issues](../../.omc/axiom/evolution/knowledge_base.md#k-079)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liangjie559567/ultrapower",
-  "version": "5.5.25",
+  "version": "5.5.26",
   "description": "Disciplined multi-agent orchestration: workflow enforcement + parallel execution",
   "type": "module",
   "main": "dist/index.js",
@@ -61,7 +61,8 @@
     "postinstall": "node scripts/plugin-setup.mjs",
     "release:local": "node scripts/release-local.mjs",
     "release:dry-run": "node scripts/release-local.mjs --dry-run",
-    "bump": "node scripts/bump-version.mjs"
+    "bump": "node scripts/bump-version.mjs",
+    "validate:versions": "node scripts/validate-versions.mjs"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.1.0",

package/scripts/plugin-setup.mjs

@@ -280,6 +280,57 @@ function fixNpmCache() {
 
 fixNpmCache();
 
+// Fix: npm-cache marketplace.json also needs repair
+function fixNpmCacheMarketplace() {
+  try {
+    const npmCacheDir = join(CLAUDE_DIR, 'plugins', 'cache', 'npm-cache', 'node_modules', '@liangjie559567', 'ultrapower');
+    if (!existsSync(npmCacheDir)) return;
+
+    const npmMarketplaceDir = join(npmCacheDir, '.claude-plugin');
+    const npmMarketplacePath = join(npmMarketplaceDir, 'marketplace.json');
+
+    let cacheVersion = '0.0.0';
+    try {
+      const cachePkg = JSON.parse(readFileSync(join(npmCacheDir, 'package.json'), 'utf-8'));
+      cacheVersion = cachePkg.version || cacheVersion;
+    } catch { /* use default */ }
+
+    function marketplaceNeedsRepair() {
+      try {
+        const content = JSON.parse(readFileSync(npmMarketplacePath, 'utf-8'));
+        if (content.name !== 'omc') return true;
+        if (!Array.isArray(content.plugins) || content.plugins.length === 0) return true;
+        return false;
+      } catch (e) {
+        if (e.code === 'ENOENT') return true;
+        return false;
+      }
+    }
+
+    if (!marketplaceNeedsRepair()) return;
+
+    const cleanMarketplaceJson = {
+      name: 'omc',
+      description: 'Disciplined multi-agent orchestration for Claude Code: workflow enforcement + parallel execution',
+      owner: { name: 'liangjie559567' },
+      plugins: [{
+        name: 'ultrapower',
+        description: 'Disciplined multi-agent orchestration: workflow enforcement + parallel execution',
+        version: cacheVersion,
+        source: { source: 'npm', package: '@liangjie559567/ultrapower', version: cacheVersion },
+        author: { name: 'liangjie559567' }
+      }]
+    };
+    mkdirSync(npmMarketplaceDir, { recursive: true });
+    writeFileSync(npmMarketplacePath, JSON.stringify(cleanMarketplaceJson, null, 2));
+    console.log(`[OMC] Repaired npm-cache marketplace.json (v${cacheVersion})`);
+  } catch (e) {
+    console.log('[OMC] Warning: Could not repair npm-cache marketplace.json:', e.message);
+  }
+}
+
+fixNpmCacheMarketplace();
+
 // Fix: Claude Code's npm-cache/package.json stores a semver range (e.g. "^5.2.3") after first install.
 // On subsequent "Update now" clicks, the installer sees the range is satisfied by the cached version
 // and skips re-downloading — so users stay on the old version forever.
@@ -390,6 +441,54 @@ function fixMissingPluginJson() {
 
 fixMissingPluginJson();
 
+// Fix: npm install strips .claude-plugin/marketplace.json, recreate it in plugin cache
+function fixMissingMarketplaceJson() {
+  try {
+    const pluginRoot = dirname(__dirname);
+    const pkgPath = join(pluginRoot, 'package.json');
+    if (!existsSync(pkgPath)) return;
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    const version = pkg.version || '0.0.0';
+
+    const marketplaceJson = {
+      name: 'omc',
+      description: 'Disciplined multi-agent orchestration for Claude Code: workflow enforcement + parallel execution',
+      owner: { name: 'liangjie559567' },
+      plugins: [{
+        name: 'ultrapower',
+        description: pkg.description || '',
+        version,
+        source: { source: 'npm', package: '@liangjie559567/ultrapower', version },
+        author: { name: 'liangjie559567' }
+      }]
+    };
+    const marketplaceJsonStr = JSON.stringify(marketplaceJson, null, 2);
+
+    // 1. Write to install dir
+    const localDir = join(pluginRoot, '.claude-plugin');
+    mkdirSync(localDir, { recursive: true });
+    writeFileSync(join(localDir, 'marketplace.json'), marketplaceJsonStr);
+    console.log('[OMC] Wrote .claude-plugin/marketplace.json in install dir');
+
+    // 2. Write to plugin cache
+    const pluginCacheBase = join(CLAUDE_DIR, 'plugins/cache/omc/ultrapower');
+    if (existsSync(pluginCacheBase)) {
+      const versions = readdirSync(pluginCacheBase);
+      for (const v of versions) {
+        const cacheDir = join(pluginCacheBase, v, '.claude-plugin');
+        mkdirSync(cacheDir, { recursive: true });
+        const versionedMkt = { ...marketplaceJson, plugins: [{ ...marketplaceJson.plugins[0], version: v, source: { ...marketplaceJson.plugins[0].source, version: v } }] };
+        writeFileSync(join(cacheDir, 'marketplace.json'), JSON.stringify(versionedMkt, null, 2));
+        console.log(`[OMC] Wrote .claude-plugin/marketplace.json in plugin cache v${v}`);
+      }
+    }
+  } catch (e) {
+    console.log('[OMC] Warning: Could not create .claude-plugin/marketplace.json:', e.message);
+  }
+}
+
+fixMissingMarketplaceJson();
+
 // 1. Create HUD directory
 if (!existsSync(HUD_DIR)) {
   mkdirSync(HUD_DIR, { recursive: true });

package/scripts/validate-versions.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// scripts/validate-versions.mjs
+// Validates version consistency across all version-bearing files
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const files = [
+  { path: 'package.json', extract: (c) => JSON.parse(c).version },
+  { path: '.claude-plugin/plugin.json', extract: (c) => JSON.parse(c).version },
+  { path: '.claude-plugin/marketplace.json', extract: (c) => JSON.parse(c).plugins?.[0]?.version },
+];
+
+function validateVersions() {
+  const versions = new Map();
+  const errors = [];
+
+  for (const { path, extract } of files) {
+    try {
+      const content = readFileSync(resolve(path), 'utf-8');
+      const version = extract(content);
+      if (!version) {
+        errors.push(`${path}: version not found`);
+        continue;
+      }
+      versions.set(path, version);
+    } catch (err) {
+      errors.push(`${path}: ${err.message}`);
+    }
+  }
+
+  if (errors.length > 0) {
+    console.error('Version validation failed:');
+    errors.forEach(e => console.error(`  - ${e}`));
+    process.exit(1);
+  }
+
+  const uniqueVersions = new Set(versions.values());
+  if (uniqueVersions.size > 1) {
+    console.error('Version mismatch detected:');
+    versions.forEach((v, p) => console.error(`  ${p}: ${v}`));
+    process.exit(1);
+  }
+
+  const version = Array.from(uniqueVersions)[0];
+  console.log(`✓ All versions in sync: ${version}`);
+  return version;
+}
+
+if (import.meta.url.startsWith('file:') && process.argv[1]) {
+  validateVersions();
+}
+
+export { validateVersions };