@pzy560117/codex-harness 0.1.0 → 0.1.2

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/ui-ux-pro-max/scripts/search.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UI/UX Pro Max Search - BM25 search engine for UI/UX style guides
+Usage: python search.py "<query>" [--domain <domain>] [--stack <stack>] [--max-results 3]
+       python search.py "<query>" --design-system [-p "Project Name"]
+       python search.py "<query>" --design-system --persist [-p "Project Name"] [--page "dashboard"]
+
+Domains: style, prompt, color, chart, landing, product, ux, typography
+Stacks: html-tailwind, react, nextjs
+
+Persistence (Master + Overrides pattern):
+  --persist    Save design system to design-system/MASTER.md
+  --page       Also create a page-specific override file in design-system/pages/
+"""
+
+import argparse
+import sys
+import io
+from core import CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, search, search_stack
+from design_system import generate_design_system, persist_design_system
+
+# Force UTF-8 for stdout/stderr to handle emojis on Windows (cp1252 default)
+if sys.stdout.encoding and sys.stdout.encoding.lower() != 'utf-8':
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+if sys.stderr.encoding and sys.stderr.encoding.lower() != 'utf-8':
+    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')
+
+
+def format_output(result):
+    """Format results for Claude consumption (token-optimized)"""
+    if "error" in result:
+        return f"Error: {result['error']}"
+
+    output = []
+    if result.get("stack"):
+        output.append(f"## UI Pro Max Stack Guidelines")
+        output.append(f"**Stack:** {result['stack']} | **Query:** {result['query']}")
+    else:
+        output.append(f"## UI Pro Max Search Results")
+        output.append(f"**Domain:** {result['domain']} | **Query:** {result['query']}")
+    output.append(f"**Source:** {result['file']} | **Found:** {result['count']} results\n")
+
+    for i, row in enumerate(result['results'], 1):
+        output.append(f"### Result {i}")
+        for key, value in row.items():
+            value_str = str(value)
+            if len(value_str) > 300:
+                value_str = value_str[:300] + "..."
+            output.append(f"- **{key}:** {value_str}")
+        output.append("")
+
+    return "\n".join(output)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="UI Pro Max Search")
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("--domain", "-d", choices=list(CSV_CONFIG.keys()), help="Search domain")
+    parser.add_argument("--stack", "-s", choices=AVAILABLE_STACKS, help="Stack-specific search (html-tailwind, react, nextjs)")
+    parser.add_argument("--max-results", "-n", type=int, default=MAX_RESULTS, help="Max results (default: 3)")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    # Design system generation
+    parser.add_argument("--design-system", "-ds", action="store_true", help="Generate complete design system recommendation")
+    parser.add_argument("--project-name", "-p", type=str, default=None, help="Project name for design system output")
+    parser.add_argument("--format", "-f", choices=["ascii", "markdown"], default="ascii", help="Output format for design system")
+    # Persistence (Master + Overrides pattern)
+    parser.add_argument("--persist", action="store_true", help="Save design system to design-system/MASTER.md (creates hierarchical structure)")
+    parser.add_argument("--page", type=str, default=None, help="Create page-specific override file in design-system/pages/")
+    parser.add_argument("--output-dir", "-o", type=str, default=None, help="Output directory for persisted files (default: current directory)")
+
+    args = parser.parse_args()
+
+    # Design system takes priority
+    if args.design_system:
+        result = generate_design_system(
+            args.query, 
+            args.project_name, 
+            args.format,
+            persist=args.persist,
+            page=args.page,
+            output_dir=args.output_dir
+        )
+        print(result)
+        
+        # Print persistence confirmation
+        if args.persist:
+            project_slug = args.project_name.lower().replace(' ', '-') if args.project_name else "default"
+            print("\n" + "=" * 60)
+            print(f"✅ Design system persisted to design-system/{project_slug}/")
+            print(f"   📄 design-system/{project_slug}/MASTER.md (Global Source of Truth)")
+            if args.page:
+                page_filename = args.page.lower().replace(' ', '-')
+                print(f"   📄 design-system/{project_slug}/pages/{page_filename}.md (Page Overrides)")
+            print("")
+            print(f"📖 Usage: When building a page, check design-system/{project_slug}/pages/[page].md first.")
+            print(f"   If exists, its rules override MASTER.md. Otherwise, use MASTER.md.")
+            print("=" * 60)
+    # Stack search
+    elif args.stack:
+        result = search_stack(args.query, args.stack, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))
+    # Domain search
+    else:
+        result = search(args.query, args.domain, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/update-codemaps/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: update-codemaps
+description: Workflow skill from update-codemaps.md
+---
+
+# Update Codemaps
+
+Analyze the codebase structure and update AI navigation documentation. Use this when a project adds modules, changes architecture boundaries, introduces generated code, external systems, sensitive directories, or asks to refresh repo maps / codemaps.
+
+## Workflow
+
+1. Identify the existing navigation surface:
+   - Prefer `docs/ai/repo-map.md` when present.
+   - Otherwise use existing `codemaps/*.md`, `docs/architecture/*`, or create `docs/ai/repo-map.md` from the package template when the user asks for a reusable navigation map.
+2. Scan source, config, tests, contracts, generated-code markers, imports, exports, and dependency boundaries. Use structured parsers or language tools when available; use `rg` for targeted discovery.
+3. Generate token-lean navigation docs. Recommended files:
+   - `docs/ai/repo-map.md` - first-read AI navigation index
+   - `codemaps/architecture.md` - overall architecture when the project already uses codemaps
+   - `codemaps/backend.md` - backend structure
+   - `codemaps/frontend.md` - frontend structure
+   - `codemaps/data.md` - data models and schemas
+4. Include, at minimum:
+   - project purpose and core domains
+   - key directories and responsibilities
+   - module entry points and truth sources
+   - generated code, sensitive paths, and do-not-edit zones
+   - external systems and MCP / API touchpoints
+   - common verification commands
+   - subdirectory `AGENTS.md` index when present
+   - freshness timestamp and maintenance owner when known
+5. Keep the map high-level. Do not explain every function or paste large source excerpts.
+6. Calculate diff percentage from the previous version when updating an existing codemap. If changes exceed 30%, summarize the reason and request user approval before replacing broad sections, unless the user explicitly asked for a full refresh.
+7. Save a short report to `.reports/codemap-diff.txt` when `.reports/` exists or when the project already uses reports.
+8. If the root `AGENTS.md` lacks a code-map entry and the project is large enough to need one, recommend adding a short link instead of copying map content into `AGENTS.md`.
+
+Use TypeScript/Node.js for JavaScript and TypeScript analysis when practical. For other stacks, prefer the project's native language tooling or LSP output when available. Focus on high-level structure, not implementation details.

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/update-docs/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: update-docs
+description: Workflow skill from update-docs.md
+---
+
+# Update Documentation
+
+Sync documentation from source-of-truth:
+
+1. Read package.json scripts section
+   - Generate scripts reference table
+   - Include descriptions from comments
+
+2. Read .env.example
+   - Extract all environment variables
+   - Document purpose and format
+
+3. Generate docs/CONTRIB.md with:
+   - Development workflow
+   - Available scripts
+   - Environment setup
+   - Testing procedures
+
+4. Generate docs/RUNBOOK.md with:
+   - Deployment procedures
+   - Monitoring and alerts
+   - Common issues and fixes
+   - Rollback procedures
+
+5. Identify obsolete documentation:
+   - Find docs not modified in 90+ days
+   - List for manual review
+
+6. Show diff summary
+
+Single source of truth: package.json and .env.example

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/verification-loop/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: verification-loop
+description: Comprehensive verification system for build, type check, lint, test, and security scanning.
+---
+
+# Verification Loop Skill
+
+A comprehensive verification system for Claude Code sessions.
+
+## When to Use
+
+Invoke this skill:
+- After completing a feature or significant code change
+- Before creating a PR
+- When you want to ensure quality gates pass
+- After refactoring
+
+## Verification Phases
+
+### Phase 1: Build Verification
+```bash
+# Check if project builds
+npm run build 2>&1 | tail -20
+# OR
+pnpm build 2>&1 | tail -20
+```
+
+If build fails, STOP and fix before continuing.
+
+### Phase 2: Type Check
+```bash
+# TypeScript projects
+npx tsc --noEmit 2>&1 | head -30
+
+# Python projects
+pyright . 2>&1 | head -30
+```
+
+Report all type errors. Fix critical ones before continuing.
+
+### Phase 3: Lint Check
+```bash
+# JavaScript/TypeScript
+npm run lint 2>&1 | head -30
+
+# Python
+ruff check . 2>&1 | head -30
+```
+
+### Phase 4: Test Suite
+```bash
+# Run tests with coverage
+npm run test -- --coverage 2>&1 | tail -50
+
+# Check coverage threshold
+# Target: 80% minimum
+```
+
+Report:
+- Total tests: X
+- Passed: X
+- Failed: X
+- Coverage: X%
+
+### Phase 5: Security Scan
+```bash
+# Check for secrets
+grep -rn "sk-" --include="*.ts" --include="*.js" . 2>/dev/null | head -10
+grep -rn "api_key" --include="*.ts" --include="*.js" . 2>/dev/null | head -10
+
+# Check for console.log
+grep -rn "console.log" --include="*.ts" --include="*.tsx" src/ 2>/dev/null | head -10
+```
+
+### Phase 6: Diff Review
+```bash
+# Show what changed
+git diff --stat
+git diff HEAD~1 --name-only
+```
+
+Review each changed file for:
+- Unintended changes
+- Missing error handling
+- Potential edge cases
+
+## Output Format
+
+After running all phases, produce a verification report:
+
+```
+VERIFICATION REPORT
+==================
+
+Build:     [PASS/FAIL]
+Types:     [PASS/FAIL] (X errors)
+Lint:      [PASS/FAIL] (X warnings)
+Tests:     [PASS/FAIL] (X/Y passed, Z% coverage)
+Security:  [PASS/FAIL] (X issues)
+Diff:      [X files changed]
+
+Overall:   [READY/NOT READY] for PR
+
+Issues to Fix:
+1. ...
+2. ...
+```
+
+## Continuous Mode
+
+For long sessions, run verification every 15 minutes or after major changes:
+
+```markdown
+Set a mental checkpoint:
+- After completing each function
+- After finishing a component
+- Before moving to next task
+
+Run: /verify
+```
+
+## Integration with Hooks
+
+This skill complements PostToolUse hooks but provides deeper verification.
+Hooks catch issues immediately; this skill provides comprehensive review.

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/verify/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: verify
+description: Workflow skill from verify.md
+---
+
+# Verification Command
+
+Run comprehensive verification on current codebase state.
+
+## Instructions
+
+Execute verification in this exact order:
+
+1. **Build Check**
+   - Run the build command for this project
+   - If it fails, report errors and STOP
+
+2. **Type Check**
+   - Run TypeScript/type checker
+   - Report all errors with file:line
+
+3. **Lint Check**
+   - Run linter
+   - Report warnings and errors
+
+4. **Test Suite**
+   - Run all tests
+   - Report pass/fail count
+   - Report coverage percentage
+
+5. **Console.log Audit**
+   - Search for console.log in source files
+   - Report locations
+
+6. **Git Status**
+   - Show uncommitted changes
+   - Show files modified since last commit
+
+## Output
+
+Produce a concise verification report:
+
+```
+VERIFICATION: [PASS/FAIL]
+
+Build:    [OK/FAIL]
+Types:    [OK/X errors]
+Lint:     [OK/X issues]
+Tests:    [X/Y passed, Z% coverage]
+Secrets:  [OK/X found]
+Logs:     [OK/X console.logs]
+
+Ready for PR: [YES/NO]
+```
+
+If any critical issues, list them with fix suggestions.
+
+## Arguments
+
+$ARGUMENTS can be:
+- `quick` - Only build + types
+- `full` - All checks (default)
+- `pre-commit` - Checks relevant for commits
+- `pre-pr` - Full checks plus security scan

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/vitest/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: vitest
+description: Vitest 测试指南
+---
+
+# Vitest 测试指南
+
+Vitest 单元测试和集成测试的配置与最佳实践。
+
+## 配置
+
+### 基础配置 (vitest.config.ts)
+
+```typescript
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['**/*.test.ts'],
+    exclude: ['**/node_modules/**', '**/dist/**'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+    },
+  },
+});
+```
+
+### E2E 配置 (vitest.e2e.config.ts)
+
+```typescript
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['tests/e2e/**/*.e2e.ts'],
+    testTimeout: 60000,
+    hookTimeout: 30000,
+    pool: 'forks',
+    poolOptions: {
+      forks: {
+        singleFork: true,
+      },
+    },
+  },
+});
+```
+
+## 测试结构
+
+### 单元测试
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { MyModule } from './MyModule';
+
+describe('MyModule', () => {
+  let module: MyModule;
+
+  beforeEach(() => {
+    module = new MyModule();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('methodName', () => {
+    it('should handle normal case', () => {
+      const result = module.methodName('input');
+      expect(result).toBe('expected');
+    });
+
+    it('should handle edge case', () => {
+      expect(() => module.methodName('')).toThrow('Invalid input');
+    });
+  });
+});
+```
+
+### 异步测试
+
+```typescript
+describe('AsyncModule', () => {
+  it('should resolve async operation', async () => {
+    const result = await asyncOperation();
+    expect(result).toBeDefined();
+  });
+
+  it('should reject on error', async () => {
+    await expect(failingOperation()).rejects.toThrow('Error message');
+  });
+});
+```
+
+## 常用断言
+
+```typescript
+// 相等性
+expect(value).toBe(expected);           // 严格相等 (===)
+expect(value).toEqual(expected);        // 深度相等
+expect(value).toStrictEqual(expected);  // 严格深度相等
+
+// 真值
+expect(value).toBeTruthy();
+expect(value).toBeFalsy();
+expect(value).toBeNull();
+expect(value).toBeUndefined();
+expect(value).toBeDefined();
+
+// 数字
+expect(value).toBeGreaterThan(3);
+expect(value).toBeGreaterThanOrEqual(3);
+expect(value).toBeLessThan(5);
+expect(value).toBeCloseTo(0.3, 5);
+
+// 字符串
+expect(value).toMatch(/pattern/);
+expect(value).toContain('substring');
+
+// 数组
+expect(array).toContain(item);
+expect(array).toHaveLength(3);
+expect(array).toEqual(expect.arrayContaining([1, 2]));
+
+// 对象
+expect(obj).toHaveProperty('key');
+expect(obj).toHaveProperty('key', 'value');
+expect(obj).toMatchObject({ key: 'value' });
+
+// 异常
+expect(() => fn()).toThrow();
+expect(() => fn()).toThrow('message');
+expect(() => fn()).toThrow(ErrorClass);
+
+// 异步
+await expect(promise).resolves.toBe(value);
+await expect(promise).rejects.toThrow();
+```
+
+## Mock
+
+### 函数 Mock
+
+```typescript
+import { vi } from 'vitest';
+
+// 创建 mock 函数
+const mockFn = vi.fn();
+mockFn.mockReturnValue('value');
+mockFn.mockResolvedValue('async value');
+mockFn.mockImplementation((x) => x * 2);
+
+// 验证调用
+expect(mockFn).toHaveBeenCalled();
+expect(mockFn).toHaveBeenCalledTimes(2);
+expect(mockFn).toHaveBeenCalledWith('arg1', 'arg2');
+```
+
+### 模块 Mock
+
+```typescript
+import { vi } from 'vitest';
+
+// Mock 整个模块
+vi.mock('./module', () => ({
+  default: vi.fn(),
+  namedExport: vi.fn(),
+}));
+
+// Mock 部分模块
+vi.mock('./module', async () => {
+  const actual = await vi.importActual('./module');
+  return {
+    ...actual,
+    specificFn: vi.fn(),
+  };
+});
+```
+
+### Spy
+
+```typescript
+import { vi } from 'vitest';
+
+const obj = {
+  method: () => 'original',
+};
+
+const spy = vi.spyOn(obj, 'method');
+spy.mockReturnValue('mocked');
+
+obj.method();  // 'mocked'
+expect(spy).toHaveBeenCalled();
+
+spy.mockRestore();  // 恢复原始实现
+```
+
+## 测试文件组织
+
+```
+src/
+├── module/
+│   ├── Module.ts
+│   ├── Module.test.ts          # 单元测试
+│   └── Module.property.test.ts # 属性测试
+tests/
+├── e2e/
+│   ├── fixtures.ts             # 测试 fixtures
+│   └── feature.e2e.ts          # E2E 测试
+└── integration/
+    └── feature.integration.ts  # 集成测试
+```
+
+## 常用命令
+
+```bash
+# 运行所有测试
+npm test
+
+# 监视模式
+npm run test:watch
+
+# 运行特定文件
+npx vitest run src/module/Module.test.ts
+
+# 运行匹配模式的测试
+npx vitest run --grep "should handle"
+
+# 覆盖率报告
+npm run test:coverage
+
+# E2E 测试
+npm run test:e2e
+```
+
+## 最佳实践
+
+1. **测试文件命名**：`*.test.ts` 或 `*.spec.ts`
+2. **测试描述清晰**：使用 `should` 开头描述预期行为
+3. **单一职责**：每个测试只验证一个行为
+4. **避免测试实现细节**：测试行为而非实现
+5. **使用 beforeEach 重置状态**：确保测试隔离
+6. **Mock 外部依赖**：文件系统、网络、数据库等
+7. **测试边界情况**：空值、边界值、异常情况
+