feat(ccw): migrate backend to TypeScript

- Convert 40 JS files to TypeScript (CLI, tools, core, MCP server)
- Add Zod for runtime parameter validation
- Add type definitions in src/types/
- Keep src/templates/ as JavaScript (dashboard frontend)
- Update bin entries to use dist/
- Add tsconfig.json with strict mode
- Add backward-compatible exports for tests
- All 39 tests passing

Breaking changes: None (backward compatible)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-12-13 10:43:15 +08:00
parent d4e59770d0
commit 25ac862f46
93 changed files with 5531 additions and 9302 deletions

View File

@@ -0,0 +1,122 @@
# Rule Template: API Rules (Backend/Fullstack Only)
## Variables
- {TECH_STACK_NAME}: Tech stack display name
- {FILE_EXT}: File extension pattern
- {API_FRAMEWORK}: API framework (Express, FastAPI, etc)
## Output Format
```markdown
---
paths:
- "**/api/**/*.{FILE_EXT}"
- "**/routes/**/*.{FILE_EXT}"
- "**/endpoints/**/*.{FILE_EXT}"
- "**/controllers/**/*.{FILE_EXT}"
- "**/handlers/**/*.{FILE_EXT}"
---
# {TECH_STACK_NAME} API Rules
## Endpoint Design
[REST/GraphQL conventions from Exa research]
### URL Structure
- Resource naming (plural nouns)
- Nesting depth limits
- Query parameter conventions
- Version prefixing
### HTTP Methods
- GET: Read operations
- POST: Create operations
- PUT/PATCH: Update operations
- DELETE: Remove operations
### Status Codes
- 2xx: Success responses
- 4xx: Client errors
- 5xx: Server errors
## Request Validation
[Input validation patterns]
### Schema Validation
```{lang}
// Example validation schema
```
### Required Fields
- Validation approach
- Error messages format
- Sanitization rules
## Response Format
[Standard response structures]
### Success Response
```json
{
"data": {},
"meta": {}
}
```
### Pagination
```json
{
"data": [],
"pagination": {
"page": 1,
"limit": 20,
"total": 100
}
}
```
## Error Responses
[Error handling for APIs]
### Error Format
```json
{
"error": {
"code": "ERROR_CODE",
"message": "Human readable message",
"details": {}
}
}
```
### Common Error Codes
- VALIDATION_ERROR
- NOT_FOUND
- UNAUTHORIZED
- FORBIDDEN
## Authentication & Authorization
[Auth patterns]
- Token handling
- Permission checks
- Rate limiting
## Documentation
[API documentation standards]
- OpenAPI/Swagger
- Inline documentation
- Example requests/responses
```
## Content Guidelines
- Focus on API-specific patterns
- Include request/response examples
- Cover security considerations
- Reference framework conventions

View File

@@ -0,0 +1,122 @@
# Rule Template: Component Rules (Frontend/Fullstack Only)
## Variables
- {TECH_STACK_NAME}: Tech stack display name
- {FILE_EXT}: File extension pattern
- {UI_FRAMEWORK}: UI framework (React, Vue, etc)
## Output Format
```markdown
---
paths:
- "**/components/**/*.{FILE_EXT}"
- "**/ui/**/*.{FILE_EXT}"
- "**/views/**/*.{FILE_EXT}"
- "**/pages/**/*.{FILE_EXT}"
---
# {TECH_STACK_NAME} Component Rules
## Component Structure
[Organization patterns from Exa research]
### File Organization
```
components/
├── common/ # Shared components
├── features/ # Feature-specific
├── layout/ # Layout components
└── ui/ # Base UI elements
```
### Component Template
```{lang}
// Standard component structure
```
### Naming Conventions
- PascalCase for components
- Descriptive names
- Prefix conventions (if any)
## Props & State
[State management guidelines]
### Props Definition
```{lang}
// Props type/interface example
```
### Props Best Practices
- Required vs optional
- Default values
- Prop validation
- Prop naming
### Local State
- When to use local state
- State initialization
- State updates
### Shared State
- State management approach
- Context usage
- Store patterns
## Styling
[CSS/styling conventions]
### Approach
- [CSS Modules/Styled Components/Tailwind/etc]
### Style Organization
```{lang}
// Style example
```
### Naming Conventions
- Class naming (BEM, etc)
- CSS variable usage
- Theme integration
## Accessibility
[A11y requirements]
### Essential Requirements
- Semantic HTML
- ARIA labels
- Keyboard navigation
- Focus management
### Testing A11y
- Automated checks
- Manual testing
- Screen reader testing
## Performance
[Performance guidelines]
### Optimization Patterns
- Memoization
- Lazy loading
- Code splitting
- Virtual lists
### Avoiding Re-renders
- When to memoize
- Callback optimization
- State structure
```
## Content Guidelines
- Focus on component-specific patterns
- Include framework-specific examples
- Cover accessibility requirements
- Address performance considerations

View File

@@ -0,0 +1,89 @@
# Rule Template: Configuration Rules
## Variables
- {TECH_STACK_NAME}: Tech stack display name
- {CONFIG_FILES}: List of config file patterns
## Output Format
```markdown
---
paths:
- "*.config.*"
- ".*rc"
- ".*rc.{js,json,yaml,yml}"
- "package.json"
- "tsconfig*.json"
- "pyproject.toml"
- "Cargo.toml"
- "go.mod"
- ".env*"
---
# {TECH_STACK_NAME} Configuration Rules
## Project Setup
[Configuration guidelines from Exa research]
### Essential Config Files
- [List primary config files]
- [Purpose of each]
### Recommended Structure
```
project/
├── [config files]
├── src/
└── tests/
```
## Tooling
[Linters, formatters, bundlers]
### Linting
- Tool: [ESLint/Pylint/etc]
- Config file: [.eslintrc/pyproject.toml/etc]
- Key rules to enable
### Formatting
- Tool: [Prettier/Black/etc]
- Integration with editor
- Pre-commit hooks
### Build Tools
- Bundler: [Webpack/Vite/etc]
- Build configuration
- Optimization settings
## Environment
[Environment management]
### Environment Variables
- Naming conventions
- Required vs optional
- Secret handling
- .env file structure
### Development vs Production
- Environment-specific configs
- Feature flags
- Debug settings
## Dependencies
[Dependency management]
- Lock file usage
- Version pinning strategy
- Security updates
- Peer dependencies
```
## Content Guidelines
- Focus on config file best practices
- Include security considerations
- Cover development workflow setup
- Mention CI/CD integration where relevant

View File

@@ -0,0 +1,60 @@
# Rule Template: Core Principles
## Variables
- {TECH_STACK_NAME}: Tech stack display name
- {FILE_EXT}: File extension pattern
## Output Format
```markdown
---
paths: **/*.{FILE_EXT}
---
# {TECH_STACK_NAME} Core Principles
## Philosophy
[Synthesize core philosophy from Exa research]
- Key paradigms and mental models
- Design philosophy
- Community conventions
## Naming Conventions
[Language-specific naming rules]
- Variables and functions
- Classes and types
- Files and directories
- Constants and enums
## Code Organization
[Structure and module guidelines]
- File structure patterns
- Module boundaries
- Import organization
- Dependency management
## Type Safety
[Type system best practices - if applicable]
- Type annotation guidelines
- Generic usage patterns
- Type inference vs explicit types
- Null/undefined handling
## Documentation
[Documentation standards]
- Comment style
- JSDoc/docstring format
- README conventions
```
## Content Guidelines
- Focus on universal principles that apply to ALL files
- Keep rules actionable and specific
- Include rationale for each rule
- Reference official style guides where applicable

View File

@@ -0,0 +1,70 @@
# Rule Template: Implementation Patterns
## Variables
- {TECH_STACK_NAME}: Tech stack display name
- {FILE_EXT}: File extension pattern
## Output Format
```markdown
---
paths: src/**/*.{FILE_EXT}
---
# {TECH_STACK_NAME} Implementation Patterns
## Common Patterns
[With code examples from Exa research]
### Pattern 1: [Name]
```{lang}
// Example code
```
**When to use**: [Context]
**Benefits**: [Why this pattern]
### Pattern 2: [Name]
...
## Anti-Patterns to Avoid
[Common mistakes with examples]
### Anti-Pattern 1: [Name]
```{lang}
// Bad example
```
**Problem**: [Why it's bad]
**Solution**: [Better approach]
## Error Handling
[Error handling conventions]
- Error types and hierarchy
- Try-catch patterns
- Error propagation
- Logging practices
## Async Patterns
[Asynchronous code conventions - if applicable]
- Promise handling
- Async/await usage
- Concurrency patterns
- Error handling in async code
## State Management
[State handling patterns]
- Local state patterns
- Shared state approaches
- Immutability practices
```
## Content Guidelines
- Focus on source code implementation
- Provide concrete code examples
- Show both good and bad patterns
- Include context for when to apply each pattern

View File

@@ -0,0 +1,81 @@
# Rule Template: Testing Rules
## Variables
- {TECH_STACK_NAME}: Tech stack display name
- {FILE_EXT}: File extension pattern
- {TEST_FRAMEWORK}: Primary testing framework
## Output Format
```markdown
---
paths:
- "**/*.{test,spec}.{FILE_EXT}"
- "tests/**/*.{FILE_EXT}"
- "__tests__/**/*.{FILE_EXT}"
- "**/test_*.{FILE_EXT}"
- "**/*_test.{FILE_EXT}"
---
# {TECH_STACK_NAME} Testing Rules
## Testing Framework
[Recommended frameworks from Exa research]
- Primary: {TEST_FRAMEWORK}
- Assertion library
- Mocking library
- Coverage tool
## Test Structure
[Organization patterns]
### File Naming
- Unit tests: `*.test.{ext}` or `*.spec.{ext}`
- Integration tests: `*.integration.test.{ext}`
- E2E tests: `*.e2e.test.{ext}`
### Test Organization
```{lang}
describe('[Component/Module]', () => {
describe('[method/feature]', () => {
it('should [expected behavior]', () => {
// Arrange
// Act
// Assert
});
});
});
```
## Mocking & Fixtures
[Best practices]
- Mock creation patterns
- Fixture organization
- Test data factories
- Cleanup strategies
## Assertions
[Assertion patterns]
- Common assertions
- Custom matchers
- Async assertions
- Error assertions
## Coverage Requirements
[Coverage guidelines]
- Minimum coverage thresholds
- What to cover vs skip
- Coverage report interpretation
```
## Content Guidelines
- Include framework-specific patterns
- Show test structure examples
- Cover both unit and integration testing
- Include async testing patterns

View File

@@ -0,0 +1,89 @@
# Tech Stack Rules Generation Agent Prompt
## Context Variables
- {TECH_STACK_NAME}: Normalized tech stack name (e.g., "typescript-react")
- {PRIMARY_LANG}: Primary language (e.g., "typescript")
- {FILE_EXT}: File extension pattern (e.g., "{ts,tsx}")
- {FRAMEWORK_TYPE}: frontend | backend | fullstack | library
- {COMPONENTS}: Array of tech components
- {OUTPUT_DIR}: .claude/rules/tech/{TECH_STACK_NAME}/
## Agent Instructions
Generate path-conditional rules for Claude Code automatic loading.
### Step 1: Execute Exa Research
Run 4-6 parallel queries based on tech stack:
**Base Queries** (always execute):
```
mcp__exa__get_code_context_exa(query: "{PRIMARY_LANG} best practices principles 2025", tokensNum: 8000)
mcp__exa__get_code_context_exa(query: "{PRIMARY_LANG} implementation patterns examples", tokensNum: 7000)
mcp__exa__get_code_context_exa(query: "{PRIMARY_LANG} testing strategies conventions", tokensNum: 5000)
mcp__exa__web_search_exa(query: "{PRIMARY_LANG} configuration setup 2025", numResults: 5)
```
**Component Queries** (for each framework in COMPONENTS):
```
mcp__exa__get_code_context_exa(query: "{PRIMARY_LANG} {component} integration patterns", tokensNum: 5000)
```
### Step 2: Read Rule Templates
Read each template file before generating content:
```
Read(~/.claude/workflows/cli-templates/prompts/rules/rule-core.txt)
Read(~/.claude/workflows/cli-templates/prompts/rules/rule-patterns.txt)
Read(~/.claude/workflows/cli-templates/prompts/rules/rule-testing.txt)
Read(~/.claude/workflows/cli-templates/prompts/rules/rule-config.txt)
Read(~/.claude/workflows/cli-templates/prompts/rules/rule-api.txt) # Only if backend/fullstack
Read(~/.claude/workflows/cli-templates/prompts/rules/rule-components.txt) # Only if frontend/fullstack
```
### Step 3: Generate Rule Files
Create directory and write files:
```bash
mkdir -p "{OUTPUT_DIR}"
```
**Always Generate**:
- core.md (from rule-core.txt template)
- patterns.md (from rule-patterns.txt template)
- testing.md (from rule-testing.txt template)
- config.md (from rule-config.txt template)
**Conditional**:
- api.md: Only if FRAMEWORK_TYPE == 'backend' or 'fullstack'
- components.md: Only if FRAMEWORK_TYPE == 'frontend' or 'fullstack'
### Step 4: Write Metadata
```json
{
"tech_stack": "{TECH_STACK_NAME}",
"primary_lang": "{PRIMARY_LANG}",
"file_ext": "{FILE_EXT}",
"framework_type": "{FRAMEWORK_TYPE}",
"components": ["{COMPONENTS}"],
"generated_at": "{ISO_TIMESTAMP}",
"source": "exa-research",
"files_generated": ["core.md", "patterns.md", "testing.md", "config.md", ...]
}
```
### Step 5: Report Completion
Provide summary:
- Files created with their path patterns
- Exa queries executed (count)
- Sources consulted (count)
## Critical Requirements
1. Every .md file MUST start with `paths` YAML frontmatter
2. Use {FILE_EXT} consistently across all rule files
3. Synthesize Exa research into actionable rules
4. Include code examples from Exa sources
5. Keep each file focused on its specific domain