@liangjie559567/ultrapower 7.5.2 → 7.7.0

package/docs/reviews/bugs-pain-points-audit/tech-debt-v7.6.0-code-review.md

@@ -0,0 +1,328 @@
+# Technical Debt Fixes v7.6.0 - Code Review Report
+
+**Review Date**: 2026-03-16
+**Commit Range**: 4f413d6d..066ff55c
+**Reviewer**: Senior Code Reviewer (Opus 4.6)
+**Scope**: 56 files, 1035 insertions, 215 deletions
+
+---
+
+## Executive Summary
+
+**Recommendation**: ⚠️ **REQUEST CHANGES**
+
+The commit range under review (4f413d6d..066ff55c) contains **only documentation changes** for TD-2. The actual code implementations for TD-1, TD-3, and TD-4 were completed in **earlier commits** (55be0ceb, 0b759af7, and pre-existing). The verification report claims all fixes are complete, but this review identifies critical issues.
+
+**Files Reviewed**: 56 (34 documentation files, 21 test event files, 1 verification report)
+
+---
+
+## Critical Findings
+
+### CRITICAL-1: Misleading Verification Report
+
+**File**: `docs/reports/tech-debt-verification-2026-03-16.md`
+**Severity**: CRITICAL
+**Issue**: The verification report claims TD-4 was fixed in the reviewed commit range, but the actual fix was implemented much earlier (likely in v7.1.1 or earlier security hardening commits).
+
+**Evidence**:
+- Report claims: "TD-4: 已完成，代码库中已正确使用原子写入"
+- Actual: `src/hooks/subagent-tracker/index.ts:427` already uses `atomicWriteJsonSyncWithRetry`
+- No TD-4 implementation commit found in range 4f413d6d..066ff55c
+
+**Impact**: Creates false audit trail, misleading for future maintenance
+
+**Recommendation**: Update verification report to clarify that TD-4 was already implemented in earlier commits, not as part of this technical debt sprint.
+
+---
+
+## Issues by Technical Debt Item
+
+### TD-1: Test Timeout Configurations ✅ VERIFIED (Earlier Commit)
+
+**Status**: Implemented correctly in commit 55be0ceb (outside review range)
+
+**Files Modified**:
+- `src/features/__tests__/mcp-integration.test.ts:10`
+- `src/features/mcp-autodiscovery/__tests__/performance.test.ts:8`
+
+**Implementation Quality**: ✅ GOOD
+```typescript
+beforeAll(async () => {
+  contextManager = new UnifiedContextManager();
+  await contextManager.initialize();
+}, 30000); // Explicit 30s timeout
+```
+
+**Verification**:
+- ✅ Timeout parameter correctly added to beforeAll hooks
+- ✅ Value appropriate (30000ms for initialization)
+- ✅ Consistent across both test files
+- ✅ Follows Vitest API correctly
+
+**Issues**: None
+
+---
+
+### TD-2: LSP Documentation Migration ⚠️ INCOMPLETE
+
+**Status**: Partially implemented in commits b06f8c59 and 7ebfcfea
+
+**Files Modified**: 34 documentation files (437 line changes)
+
+**Implementation Quality**: ⚠️ NEEDS IMPROVEMENT
+
+#### HIGH-1: Inconsistent Tool Name Format
+
+**Files**: Multiple documentation files
+**Line**: Various
+**Issue**: Documentation shows tool names as `mcp__plugin_ultrapower_t__lsp_*` which creates confusion.
+
+**Example from docs/REFERENCE.md:820**:
+```markdown
+| `ultrapower:lsp_hover` | `mcp__plugin_ultrapower_t__lsp_hover` |
+```
+
+**Problem**: The MCP tool name contains a colon in the middle: `...t__ultrapower:lsp_hover`
+
+**Expected**: Either:
+1. `mcp__plugin_ultrapower_t__lsp_hover` (if keeping old naming)
+2. Document that the actual MCP name uses underscores: `mcp__plugin_ultrapower_t__ultrapower_lsp_hover`
+
+**Impact**: Users will get tool not found errors if they copy-paste these names
+
+**Recommendation**: Verify actual MCP tool registration names in `src/tools/lsp-tools.ts` and ensure documentation matches exactly.
+
+---
+
+#### MEDIUM-1: Incomplete Migration in Code Examples
+
+**File**: `docs/mcp/performance.md:61-64`
+**Issue**: Code examples use invalid syntax with colons in object property access
+
+```typescript
+// Current (INVALID JavaScript):
+const [hover, refs, symbols] = await Promise.all([
+  mcp__plugin_ultrapower_t__lsp_hover({ file, line, character }),
+  //                                   ^ SyntaxError: Unexpected token ':'
+```
+
+**Expected**:
+```typescript
+const [hover, refs, symbols] = await Promise.all([
+  mcp__plugin_ultrapower_t__['ultrapower:lsp_hover']({ file, line, character }),
+  // OR if the actual tool name uses underscores:
+  mcp__plugin_ultrapower_t__ultrapower_lsp_hover({ file, line, character }),
+]);
+```
+
+**Impact**: Code examples will not run, causing user confusion
+
+**Recommendation**: Fix all code examples to use valid JavaScript syntax.
+
+---
+
+#### MEDIUM-2: Missing Verification Step
+
+**File**: Plan specified grep verification, but no evidence it was run
+**Issue**: Plan step 3 says: `grep -r "ultrapower:lsp_diagnostics" docs/`
+
+**Problem**: This grep would find the NEW naming (which is correct), but the plan description says "Expected: No matches" which is backwards logic.
+
+**Recommendation**: Clarify verification steps and provide evidence that old naming (`lsp_*` without prefix) no longer exists in documentation.
+
+---
+
+### TD-3: Windows Compatibility Tests ✅ VERIFIED (Earlier Commit)
+
+**Status**: Implemented correctly in commit 0b759af7 (outside review range)
+
+**Files Created**:
+- `tests/platform/windows-atomic-write.test.ts` (30 lines)
+- `docs/standards/runtime-protection.md` (7 lines added)
+
+**Implementation Quality**: ✅ GOOD
+
+**Code Review**:
+```typescript
+describe.skipIf(process.platform !== 'win32')('Windows atomic write', () => {
+  // ✅ Correct platform detection
+  // ✅ Proper cleanup in afterEach
+  // ✅ Tests actual atomic write behavior
+
+  it('should handle locked files gracefully', () => {
+    atomicWriteJsonSyncWithRetry(testPath, data);
+    expect(existsSync(testPath)).toBe(true);
+    // ✅ Verifies file was written
+    // ✅ Verifies content integrity
+  });
+});
+```
+
+**Strengths**:
+- ✅ Uses `skipIf` for platform detection (correct Vitest API)
+- ✅ Proper cleanup with `afterEach` and `testFiles` tracking
+- ✅ Tests the actual atomic write function
+- ✅ Documentation updated with platform notes
+
+**Issues**: None
+
+---
+
+### TD-4: Atomic Write Protection ⚠️ MISLEADING CLAIM
+
+**Status**: Already implemented (pre-existing, not in this sprint)
+
+**Files**: `src/hooks/subagent-tracker/index.ts:427`
+
+**Implementation Quality**: ✅ GOOD (but not part of this review)
+
+**Current State**:
+```typescript
+// Line 12: Import present
+import { atomicWriteJsonSyncWithRetry } from "../../lib/atomic-write.js";
+
+// Line 427: Correct usage
+atomicWriteJsonSyncWithRetry(statePath, state);
+```
+
+**Issue**: The verification report claims this was fixed as part of TD-4, but:
+- No commit in range 4f413d6d..066ff55c modifies `subagent-tracker/index.ts`
+- The atomic write was likely implemented during v7.1.1 security hardening
+- Commit fc63ee7d (feat(security): implement hook system security hardening) predates this sprint
+
+**Recommendation**: Update verification report to acknowledge TD-4 was already complete, not newly implemented.
+
+---
+
+## Security Review
+
+### No Security Issues Found
+
+All changes in this commit range are documentation-only (TD-2). The code changes (TD-1, TD-3, TD-4) were in earlier commits and have been reviewed separately.
+
+---
+
+## Performance Review
+
+### No Performance Impact
+
+Documentation changes have no runtime performance impact.
+
+---
+
+## Best Practices Review
+
+### LOW-1: Commit Range Mismatch
+
+**Issue**: The verification report references commit range 4f413d6d..066ff55c, but the actual implementation commits (55be0ceb, 0b759af7, b06f8c59, 7ebfcfea) are outside or partially outside this range.
+
+**Impact**: Confusing audit trail for future reviews
+
+**Recommendation**: Either:
+1. Expand commit range to include all implementation commits
+2. Clarify that verification covers earlier commits, not just the specified range
+
+---
+
+### LOW-2: Test Event Files in Review
+
+**Files**: 21 files in `.omc/nexus/events/`
+**Issue**: Test event JSON files are included in the commit range, adding noise to the review
+
+**Recommendation**: Consider `.gitignore` for test event files or use separate commits for test artifacts.
+
+---
+
+## Documentation Quality
+
+### MEDIUM-3: Inconsistent Terminology
+
+**Files**: Multiple documentation files
+**Issue**: Mixed use of "LSP tools", "LSP tool naming", "ultrapower:lsp_*" without clear definition
+
+**Recommendation**: Add a glossary section explaining:
+- What "ultrapower:" prefix means
+- Why the migration is happening
+- How to identify old vs new naming
+
+---
+
+## Summary Statistics
+
+| Category | Count |
+|----------|-------|
+| **Files Reviewed** | 56 |
+| **Code Files** | 0 (all in earlier commits) |
+| **Documentation Files** | 34 |
+| **Test Files** | 0 (created in earlier commit) |
+| **Test Event Files** | 21 |
+| **Critical Issues** | 1 |
+| **High Issues** | 1 |
+| **Medium Issues** | 3 |
+| **Low Issues** | 2 |
+
+---
+
+## Issues by Severity
+
+### CRITICAL (1)
+- **CRITICAL-1**: Misleading verification report claims TD-4 was fixed in this sprint
+
+### HIGH (1)
+- **HIGH-1**: Invalid MCP tool names in documentation (contains colons)
+
+### MEDIUM (3)
+- **MEDIUM-1**: Code examples use invalid JavaScript syntax
+- **MEDIUM-2**: Missing verification evidence for old naming removal
+- **MEDIUM-3**: Inconsistent terminology across documentation
+
+### LOW (2)
+- **LOW-1**: Commit range mismatch in verification report
+- **LOW-2**: Test event files add noise to review
+
+---
+
+## Approval Recommendation
+
+⚠️ **REQUEST CHANGES**
+
+### Must Fix Before Approval:
+1. **CRITICAL-1**: Update verification report to clarify TD-4 was pre-existing
+2. **HIGH-1**: Fix MCP tool names in documentation (remove colons or use bracket notation)
+3. **MEDIUM-1**: Fix all code examples to use valid JavaScript syntax
+
+### Should Fix (Recommended):
+4. **MEDIUM-2**: Provide evidence that old LSP naming is removed from docs
+5. **MEDIUM-3**: Add terminology glossary for LSP tool naming
+
+### Nice to Have:
+6. **LOW-1**: Clarify commit range scope in verification report
+7. **LOW-2**: Consider gitignoring test event files
+
+---
+
+## Positive Observations
+
+1. ✅ TD-1 implementation is clean and correct (commit 55be0ceb)
+2. ✅ TD-3 Windows test has proper platform detection and cleanup (commit 0b759af7)
+3. ✅ TD-4 atomic write protection is correctly implemented (pre-existing)
+4. ✅ CHANGELOG deprecation notice is clear (commit b06f8c59)
+5. ✅ Documentation migration is comprehensive (437 line changes)
+6. ✅ Commit messages follow conventional commits format
+
+---
+
+## Next Steps
+
+1. Fix HIGH-1 and MEDIUM-1 by verifying actual MCP tool registration names
+2. Update verification report to correct TD-4 timeline
+3. Run verification: `grep -rn "mcp__plugin_ultrapower_t__lsp_" docs/` to find old naming
+4. Fix code examples to use valid syntax
+5. Re-run full test suite to ensure no regressions
+6. Update this review with fixes and re-submit for approval
+
+---
+
+**Review Completed**: 2026-03-16T20:10:05Z
+**Reviewer**: Senior Code Reviewer (Claude Opus 4.6)

package/docs/security/command-injection-scan.md

@@ -0,0 +1,223 @@
+# 命令注入扫描报告
+
+## 扫描摘要
+- 发现命令执行点: 37
+- Windows 风险点: 6
+- 安全使用点: 31
+
+## Windows 平台风险点
+
+### 1. src/mcp/codex-core.ts:230
+```typescript
+const child = spawn(codexCmd, args, {
+  stdio: ['pipe', 'pipe', 'pipe'],
+  ...(cwd ? { cwd } : {}),
+  shell: process.platform === 'win32',
+  env: getSpawnEnv()
+});
+```
+**风险**: Windows 平台启用 shell，可能导致命令注入
+**平台**: Windows
+**修复建议**:
+- 验证 `codexCmd` 来源（通过 `getCliCommand('codex')` 获取）
+- 确保 `args` 数组元素已消毒
+- 考虑使用 `execFile` 或禁用 shell
+
+### 2. src/mcp/gemini-core.ts:114
+```typescript
+const child = spawn(getCliCommand('gemini'), args, {
+  stdio: ['pipe', 'pipe', 'pipe'],
+  ...(cwd ? { cwd } : {}),
+  shell: process.platform === 'win32',
+  env: getSpawnEnv()
+});
+```
+**风险**: Windows 平台启用 shell，可能导致命令注入
+**平台**: Windows
+**修复建议**:
+- 验证 `getCliCommand('gemini')` 返回值
+- 确保 `args` 数组元素已消毒
+- 考虑使用 `execFile` 或禁用 shell
+
+### 3. src/mcp/gemini-core.ts:217
+```typescript
+const child = spawn(getCliCommand('gemini'), args, {
+  stdio: ['pipe', 'pipe', 'pipe'],
+  ...(cwd ? { cwd } : {}),
+  shell: process.platform === 'win32',
+  env: getSpawnEnv()
+});
+```
+**风险**: Windows 平台启用 shell（后台模式）
+**平台**: Windows
+**修复建议**: 同上
+
+### 4. src/mcp/codex-core.ts:408
+```typescript
+const child = spawn(getCliCommand('codex'), args, {
+  stdio: ['pipe', 'pipe', 'pipe'],
+  ...(cwd ? { cwd } : {}),
+  shell: process.platform === 'win32',
+  env: getSpawnEnv()
+});
+```
+**风险**: Windows 平台启用 shell（后台模式）
+**平台**: Windows
+**修复建议**: 同上
+
+### 5. src/tools/lsp/client.ts:202
+```typescript
+this.process = spawn(this.serverConfig.command, this.serverConfig.args, {
+  cwd: this.workspaceRoot,
+  stdio: ['pipe', 'pipe', 'pipe'],
+  // On Windows, npm-installed binaries are .cmd scripts that require
+  // shell execution. Without this, spawn() fails with ENOENT. (#569)
+  shell: process.platform === 'win32'
+});
+```
+**风险**: Windows 平台启用 shell 以支持 .cmd 脚本
+**平台**: Windows
+**修复建议**:
+- 验证 `this.serverConfig.command` 和 `this.serverConfig.args` 来源
+- 实施白名单验证 LSP 服务器命令
+- 考虑使用 `execFile` 或路径规范化
+
+### 6. src/compatibility/mcp-bridge.ts:178
+```typescript
+const child = spawn(config.command, config.args || [], {
+  env: safeEnv,
+  stdio: ['pipe', 'pipe', 'pipe'],
+});
+```
+**风险**: 未显式禁用 shell，在某些平台可能启用
+**平台**: 跨平台
+**修复建议**:
+- 显式设置 `shell: false`
+- 验证 `config.command` 和 `config.args` 来源
+- 实施 MCP 配置白名单
+
+## 安全使用点（参数数组形式）
+
+以下使用点使用参数数组且未启用 shell，相对安全：
+
+1. **测试文件** (11 个)
+   - tests/security/penetration.test.ts:10
+   - tests/hooks/bridge-input-validation.test.ts:10
+   - tests/security/fuzzing.test.ts:10
+   - tests/integration/input-validation.test.ts:10
+   - tests/integration/hook-input-security.test.ts:10
+   - tests/brainstorm-server/server.test.js:33
+   - src/notifications/__tests__/session-registry.test.ts:42
+   - scripts/test-remember-tags.ts:16
+   - src/hooks/persistent-mode/__tests__/error-handling.test.ts:51
+
+2. **工具链** (5 个)
+   - benchmarks/run.ts:12 - `spawn('tsx', [script])`
+   - src/features/assumption-validator/lsp-checker.ts:10 - `spawn('npx', ['tsc', '--noEmit', filePath])`
+   - src/cli/utils/tokscale-launcher.ts:13 - `spawn('bunx', ['tokscale@latest', '--version'])`
+   - src/cli/utils/tokscale-launcher.ts:49 - `spawn('bunx', args)`
+
+3. **内部服务** (4 个)
+   - src/tools/python-repl/bridge-manager.ts:322 - Python REPL 桥接
+   - src/team/mcp-team-bridge.ts:355 - MCP 团队桥接
+   - src/notifications/reply-listener.ts:854 - 守护进程启动
+   - src/features/rate-limit-wait/daemon.ts:466 - 速率限制守护进程
+
+## 修复优先级
+
+### P0 - 立即修复
+1. **src/mcp/codex-core.ts:230, 408** - Codex CLI 调用
+2. **src/mcp/gemini-core.ts:114, 217** - Gemini CLI 调用
+3. **src/tools/lsp/client.ts:202** - LSP 客户端启动
+
+### P1 - 高优先级
+4. **src/compatibility/mcp-bridge.ts:178** - MCP 桥接
+
+## 修复建议
+
+### 通用修复模式
+
+```typescript
+// 不安全 (Windows 启用 shell)
+spawn(command, args, { shell: process.platform === 'win32' });
+
+// 安全方案 1: 使用 execFile
+import { execFile } from 'child_process';
+execFile(command, args, options, callback);
+
+// 安全方案 2: 显式禁用 shell + 路径验证
+import { resolve } from 'path';
+const safePath = resolve(command); // 规范化路径
+spawn(safePath, args, { shell: false });
+
+// 安全方案 3: 白名单验证
+const ALLOWED_COMMANDS = ['codex', 'gemini', 'typescript-language-server'];
+if (!ALLOWED_COMMANDS.includes(basename(command))) {
+  throw new Error('Unauthorized command');
+}
+```
+
+### 针对性修复
+
+#### 1. MCP CLI 工具 (codex/gemini)
+```typescript
+// 添加命令白名单验证
+function getCliCommand(tool: 'codex' | 'gemini'): string {
+  const cmd = tool === 'codex' ? 'codex' : 'gemini';
+  // 验证命令存在且安全
+  return cmd;
+}
+
+// 参数消毒
+function sanitizeArgs(args: string[]): string[] {
+  return args.map(arg => {
+    // 移除危险字符
+    if (arg.includes(';') || arg.includes('&') || arg.includes('|')) {
+      throw new Error('Invalid argument');
+    }
+    return arg;
+  });
+}
+```
+
+#### 2. LSP 客户端
+```typescript
+// 实施 LSP 服务器白名单
+const ALLOWED_LSP_SERVERS = [
+  'typescript-language-server',
+  'vscode-json-languageserver',
+  'pyright'
+];
+
+function validateLspCommand(command: string): void {
+  const basename = path.basename(command, '.cmd');
+  if (!ALLOWED_LSP_SERVERS.includes(basename)) {
+    throw new Error(`Unauthorized LSP server: ${command}`);
+  }
+}
+```
+
+#### 3. MCP 桥接
+```typescript
+// 显式禁用 shell
+const child = spawn(config.command, config.args || [], {
+  env: safeEnv,
+  stdio: ['pipe', 'pipe', 'pipe'],
+  shell: false // 显式禁用
+});
+```
+
+## 验证清单
+
+- [ ] 所有 Windows 风险点已修复
+- [ ] 实施命令白名单验证
+- [ ] 参数消毒机制就位
+- [ ] 添加单元测试覆盖命令注入场景
+- [ ] 更新安全文档
+- [ ] 代码审查通过
+
+## 参考资料
+
+- [OWASP Command Injection](https://owasp.org/www-community/attacks/Command_Injection)
+- [Node.js child_process Security](https://nodejs.org/api/child_process.html#child_process_spawning_bat_and_cmd_files_on_windows)
+- CWE-78: OS Command Injection