claude-flow-novice 2.18.5 → 2.18.6

package/.claude/skills/cfn-compilation-error-fixer/SKILL.md

@@ -0,0 +1,426 @@
+---
+name: cfn-compilation-error-fixer
+description: Two-phase compilation error fixer for Rust and TypeScript using Cerebras LLM bulk processing + dedicated agent cleanup
+version: 2.0.0
+tags: [rust, typescript, compilation, cerebras, error-fixer, cfn]
+status: production
+---
+
+# CFN Compilation Error Fixer
+
+Two-phase workflow for fixing large-scale compilation errors in Rust and TypeScript projects using Cerebras LLM bulk processing + dedicated agent cleanup.
+
+## Skill Structure
+
+```
+.claude/skills/cfn-compilation-error-fixer/
+├── SKILL.md                          # This file
+├── HANDOFF.md                        # Detailed handoff documentation
+├── package.json                      # Dependencies and npm scripts
+├── index.js                          # Main entry point
+├── bin/
+│   └── fix-errors.sh                 # Executable script
+├── lib/
+│   └── fixer/
+│       ├── package.json              # Runtime dependencies
+│       ├── cerebras-wrapper.ts       # Cerebras SDK wrapper
+│       ├── cerebras-gated-fixer-v2.ts # Rust fixer (self-contained)
+│       ├── typescript-gated-fixer-v2.ts # TypeScript fixer (self-contained)
+│       └── tsconfig.json             # TypeScript configuration
+└── lib/
+    └── gates/
+        └── typescript-gates.ts       # TypeScript validation gates
+```
+
+## Overview
+
+This skill orchestrates:
+1. **Phase 1**: Cerebras LLM bulk fixer (fast, cheap, ~95%+ reduction)
+2. **Phase 2**: Dedicated CFN agent (high quality cleanup)
+
+## Phase 1: Cerebras Bulk Fixer
+
+### When to Use
+- 20+ compilation errors
+- Need fast bulk reduction
+- Errors are mostly mechanical (type mismatches, missing imports, syntax issues)
+- Both Rust and TypeScript projects supported
+
+### How to Run - Rust
+
+```bash
+# Setup (one-time)
+cd /mnt/c/Users/masha/Documents/claude-flow-novice/.claude/skills/cfn-compilation-error-fixer
+npm install
+
+# Option 1: Run from skill directory
+export CEREBRAS_API_KEY="your-key"
+npm run fix:rust
+
+# Option 2: Run from your Rust project directory
+cd /path/to/your/rust-project
+export CEREBRAS_API_KEY="your-key"
+npx tsx /mnt/c/Users/masha/Documents/claude-flow-novice/.claude/skills/cfn-compilation-error-fixer/lib/fixer/cerebras-gated-fixer-v2.ts
+
+# Option 3: Use the executable script
+./bin/fix-errors.sh rust
+
+# Option 4: Use Node.js entry point
+node index.js rust
+
+# Additional flags
+npm run fix:rust -- --dry-run        # Preview patches without writing
+npm run fix:rust -- --verbose        # Debug output
+npm run fix:rust -- --no-layer3      # Skip LLM review layer
+npm run fix:rust -- --no-clippy      # Skip clippy checks
+
+# With explicit project path
+npx tsx cerebras-gated-fixer-v2.ts --project=/path/to/rust-project
+
+# With environment variable
+export RUST_PROJECT_PATH=/path/to/rust-project
+npx tsx cerebras-gated-fixer-v2.ts
+```
+
+### How to Run - TypeScript
+
+```bash
+# Setup (one-time)
+cd /mnt/c/Users/masha/Documents/claude-flow-novice/.claude/skills/cfn-compilation-error-fixer
+npm install
+
+# Option 1: Run from skill directory
+export CEREBRAS_API_KEY="your-key"
+npm run fix:ts
+
+# Option 2: Run from your TypeScript project directory
+cd /path/to/your/typescript-project
+export CEREBRAS_API_KEY="your-key"
+npx tsx /mnt/c/Users/masha/Documents/claude-flow-novice/.claude/skills/cfn-compilation-error-fixer/lib/fixer/typescript-gated-fixer-v2.ts
+
+# Option 3: Use the executable script
+./bin/fix-errors.sh typescript
+./bin/fix-errors.sh ts  # Short form
+
+# Option 4: Use Node.js entry point
+node index.js typescript
+node index.js ts
+
+# Additional flags
+npm run fix:ts -- --dry-run          # Preview patches without writing
+npm run fix:ts -- --verbose          # Debug output
+
+# With explicit project path
+npx tsx typescript-gated-fixer-v2.ts --project=/path/to/typescript-project
+```
+
+### Architecture
+
+```
+┌─────────────────┐
+│  cargo check    │ → Parse Rust errors
+└────────┬────────┘
+         ▼
+┌─────────────────┐
+│ Cerebras LLM    │ → Generate fix (zai-glm-4.6)
+└────────┬────────┘
+         ▼
+┌─────────────────────────────────────────┐
+│     LAYER 1: 12 Structural Gates        │
+├─────────────────────────────────────────┤
+│ A: LineCount    B: FnSignature          │
+│ C: ImportDup    D: BraceBalance         │
+│ E: SemanticDiff F: OrphanedCode         │
+│ G: ImportPath   H: PatternDup           │
+│ I: ImplLocation J: TypeCast             │
+│ K: MatchArm     L: Regression           │
+└────────┬────────────────────────────────┘
+         ▼ (up to 3 retries with feedback)
+┌─────────────────────────────────────────┐
+│     LAYER 2: cargo check validation     │
+└────────┬────────────────────────────────┘
+         ▼
+┌─────────────────────────────────────────┐
+│     LAYER 3: LLM Review Gate            │
+└────────┬────────────────────────────────┘
+         ▼
+┌─────────────────┐
+│  Write to file  │
+└─────────────────┘
+```
+
+### Expected Results
+
+#### Rust
+- **Input**: 200+ errors
+- **Output**: 10-20 errors (95%+ reduction)
+- **Quality**: 4-5/10 (some semantic issues)
+
+#### TypeScript
+- **Input**: 100+ errors
+- **Output**: 5-10 errors (95%+ reduction)
+- **Quality**: 4-5/10 (some semantic issues)
+
+### Logs
+- `/tmp/rust-fix-patches/` - Rust fix patches directory
+- `/tmp/typescript-fix-patches/` - TypeScript fix patches directory
+- `/tmp/v2-retry-run.log` - Full run output
+- `/tmp/gate-rejections.json` - Gate rejection details
+- Console output with detailed progress
+
+---
+
+## Phase 2: Dedicated Agent Cleanup
+
+### When to Use
+- After Phase 1 completes
+- <20 errors remaining (Rust) or <10 errors (TypeScript)
+- Need high-quality fixes (8-10/10)
+- Errors are semantic or complex
+
+### How to Invoke - Rust
+
+Spawn a rust-developer or cfn-system-expert agent with this prompt:
+
+```
+You are a Rust compilation error fixer. Fix the remaining errors in the Rust codebase.
+
+CONTEXT:
+- Cerebras LLM already fixed ~95% of errors
+- Quality validation found some semantic issues in applied fixes
+- Remaining errors need high-quality fixes
+
+WORKING DIRECTORY:
+cd <YOUR_RUST_PROJECT_PATH>  # e.g., /path/to/rust-project
+
+STEP 1: Get current error count and locations
+SQLX_OFFLINE=true cargo check 2>&1 | grep -E "^error\[E" | sort | uniq -c | sort -rn
+
+STEP 2: For each error file, fix in order of dependency:
+1. Read the FULL file to understand context
+2. Identify the root cause (not just the symptom)
+3. Apply minimal fix that preserves semantics
+4. Run SQLX_OFFLINE=true cargo check to verify
+5. If new errors appear, fix those too
+
+RULES:
+- Read FULL file before editing (not just error snippets)
+- Preserve ALL existing imports, don't duplicate
+- Use proper Rust idioms (? operator, as casts, trait bounds)
+- Fix root causes first (cascading errors will resolve)
+- Verify with cargo check after EACH file
+- Maintain CFN compliance standards
+
+COMMON ERROR TYPES:
+- E0308 (type mismatch): Add explicit casts or fix generics
+- E0412/E0433/E0425 (missing type/import): Add use statements
+- E0599 (wrong method): Fix method chain (e.g., .ok_or_else() on Result)
+- E0277 (trait not implemented): Add trait implementations
+- E0382 (borrow checker): Fix ownership issues
+
+Report final error count when done.
+```
+
+### How to Invoke - TypeScript
+
+Spawn a typescript-developer or cfn-system-expert agent with this prompt:
+
+```
+You are a TypeScript compilation error fixer. Fix the remaining errors in the TypeScript codebase.
+
+CONTEXT:
+- Cerebras LLM already fixed ~95% of errors
+- Quality validation found some semantic issues in applied fixes
+- Remaining errors need high-quality fixes
+
+WORKING DIRECTORY:
+cd <YOUR_TYPESCRIPT_PROJECT_PATH>  # e.g., /path/to/typescript-project
+
+STEP 1: Get current error count and locations
+npm run type-check 2>&1 | grep -E "error TS" | sort | uniq -c | sort -rn
+
+STEP 2: For each error file, fix in order of dependency:
+1. Read the FULL file to understand context
+2. Identify the root cause (not just the symptom)
+3. Apply minimal fix that preserves semantics
+4. Run npm run type-check to verify
+5. If new errors appear, fix those too
+
+RULES:
+- Read FULL file before editing (not just error snippets)
+- Preserve ALL existing imports, don't duplicate
+- Use proper TypeScript idioms (type guards, interfaces, generics)
+- Fix root causes first (cascading errors will resolve)
+- Verify with tsc after EACH file
+- Maintain CFN compliance standards
+
+COMMON ERROR TYPES:
+- TS2307 (module not found): Fix import paths or install missing packages
+- TS2322 (type mismatch): Add type annotations or fix type inference
+- TS2339 (property not exists): Add interface definitions or type assertions
+- TS7006 (implicit any): Add explicit type annotations
+- TS2688 (cannot find type definition): Install @types packages
+
+Report final error count when done.
+```
+
+### Expected Results
+- **Input**: 10-20 errors (Rust) or 5-10 errors (TypeScript)
+- **Output**: 0 errors
+- **Quality**: 9-10/10
+
+---
+
+## Full Workflow Example
+
+### Rust Workflow
+
+```bash
+# 1. Check initial error count
+cd <YOUR_RUST_PROJECT_PATH>
+SQLX_OFFLINE=true cargo check 2>&1 | grep -c "^error\["
+# Output: 342
+
+# 2. Run Phase 1 (Cerebras bulk fixer)
+cd /mnt/c/Users/masha/Documents/claude-flow-novice/.claude/skills/cfn-compilation-error-fixer
+export CEREBRAS_API_KEY="your-key"
+npm run fix:rust 2>&1 | tee /tmp/rust-fix.log
+# Output: 342 → 15 (95.6% reduction)
+
+# 3. Validate Phase 1 results
+cd <YOUR_RUST_PROJECT_PATH>
+SQLX_OFFLINE=true cargo check 2>&1 | grep -E "^error\[" | wc -l
+# Output: 15
+
+# 4. Run Phase 2 (dedicated agent cleanup)
+# Spawn rust-developer agent with prompt above
+# Output: 15 → 0
+
+# 5. Final verification
+SQLX_OFFLINE=true cargo check
+# Output: Finished dev profile [unoptimized + debuginfo] target(s) in X.XXs
+```
+
+### TypeScript Workflow
+
+```bash
+# 1. Check initial error count
+cd <YOUR_TYPESCRIPT_PROJECT_PATH>
+npm run type-check 2>&1 | grep -c "error TS"
+# Output: 156
+
+# 2. Run Phase 1 (Cerebras bulk fixer)
+cd /mnt/c/Users/masha/Documents/claude-flow-novice/.claude/skills/cfn-compilation-error-fixer
+export CEREBRAS_API_KEY="your-key"
+npm run fix:ts 2>&1 | tee /tmp/typescript-fix.log
+# Output: 156 → 7 (95.5% reduction)
+
+# 3. Validate Phase 1 results
+cd <YOUR_TYPESCRIPT_PROJECT_PATH>
+npm run type-check 2>&1 | grep "error TS" | wc -l
+# Output: 7
+
+# 4. Run Phase 2 (dedicated agent cleanup)
+# Spawn typescript-developer agent with prompt above
+# Output: 7 → 0
+
+# 5. Final verification
+npm run type-check
+# Output: No type errors found
+```
+
+---
+
+## Files Reference
+
+| File | Purpose |
+|------|---------|
+| `./HANDOFF.md` | Detailed handoff documentation |
+| `./lib/fixer/cerebras-gated-fixer-v2.ts` | Rust fixer (self-contained) |
+| `./lib/fixer/typescript-gated-fixer-v2.ts` | TypeScript fixer (self-contained) |
+| `./lib/gates/typescript-gates.ts` | TypeScript validation gates |
+| `./bin/fix-errors.sh` | Executable wrapper script |
+| `./index.js` | Node.js entry point |
+| `/tmp/gate-rejections.json` | Gate rejection log (runtime) |
+| `/tmp/v2-retry-run.log` | Full run output (runtime) |
+| `/tmp/rust-fix-patches/` | Rust fix patches (runtime) |
+| `/tmp/typescript-fix-patches/` | TypeScript fix patches (runtime) |
+
+## Environment Requirements
+
+### System Requirements
+- Node.js 18+
+- Rust 1.70.0+ (for Rust projects)
+- TypeScript 4.5+ (for TypeScript projects)
+
+### Environment Variables
+- `CEREBRAS_API_KEY`: Your Cerebras API key (required for LLM fixes)
+- `CFN_ALLOW_FALLBACK=true`: Allow running without Cerebras SDK (read-only mode)
+- `SQLX_OFFLINE=true`: For cargo check without database (Rust projects)
+- `RUST_PROJECT_PATH`: Override default Rust project path
+- `TYPESCRIPT_PROJECT_PATH`: Override default TypeScript project path
+
+### Default Project Paths
+- Rust: `/mnt/c/Users/masha/Documents/ourstories-v2/services/rust-services`
+- TypeScript: Current working directory
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"tsx is not installed"**
+   ```bash
+   npm install -g tsx
+   # Or use local version
+   npx tsx [file]
+   ```
+
+2. **"Cerebras SDK not found"**
+   - Install the SDK: `npm install @cerebras/cerebras_cloud_sdk`
+   - Or use fallback mode: `CFN_ALLOW_FALLBACK=true npm run fix:rust`
+
+3. **Permission denied on fix-errors.sh**
+   ```bash
+   chmod +x bin/fix-errors.sh
+   ```
+
+4. **"Module not found" errors**
+   ```bash
+   cd /mnt/c/Users/masha/Documents/claude-flow-novice/.claude/skills/cfn-compilation-error-fixer
+   npm install
+   ```
+
+5. **High memory usage**
+   - Use `--max-tokens 2000` to limit LLM response size
+   - Process errors in smaller batches
+
+### Debug Mode
+
+Enable verbose logging to see detailed processing:
+```bash
+npm run fix:rust -- --verbose
+npm run fix:ts -- --verbose
+```
+
+### Performance Tuning
+
+- For large codebases (500+ errors): Use `--parallel-calls 5` to reduce API calls
+- For slow systems: Use `--no-layer3` to skip LLM review
+- For quick testing: Use `--dry-run` to preview fixes
+
+### Recovery
+
+If fixes break the build:
+```bash
+# Rust
+cd <RUST_PROJECT>
+git checkout -- src/
+SQLX_OFFLINE=true cargo check
+
+# TypeScript
+cd <TYPESCRIPT_PROJECT>
+git checkout -- src/
+npm run type-check
+```

package/.claude/skills/cfn-compilation-error-fixer/bin/fix-errors.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+set -eu
+
+# CFN Compilation Error Fixer
+# Usage: ./fix-errors.sh [rust|typescript] [options]
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# Default to Rust fixer
+FIXER_TYPE="${1:-rust}"
+shift
+
+# Show help
+if [[ "${FIXER_TYPE}" == "--help" ]] || [[ "${FIXER_TYPE}" == "-h" ]]; then
+    echo "CFN Compilation Error Fixer"
+    echo ""
+    echo "Usage:"
+    echo "  fix-errors.sh [rust|typescript] [options]"
+    echo ""
+    echo "Examples:"
+    echo "  fix-errors.sh rust                    # Fix Rust errors"
+    echo "  fix-errors.sh rust --dry-run         # Dry run for Rust"
+    echo "  fix-errors.sh typescript             # Fix TypeScript errors"
+    echo "  fix-errors.sh ts --verbose           # Verbose TypeScript fixing"
+    echo ""
+    echo "Options:"
+    echo "  --dry-run     Show what would be fixed without making changes"
+    echo "  --verbose     Show detailed output"
+    echo "  --help, -h    Show this help message"
+    exit 0
+fi
+
+# Map short aliases
+case "$FIXER_TYPE" in
+    "ts")
+        FIXER_TYPE="typescript"
+        ;;
+    "rust"|"typescript")
+        # Valid types
+        ;;
+    *)
+        echo "Error: Invalid fixer type '$FIXER_TYPE'"
+        echo "Use 'rust' or 'typescript' (or 'ts')"
+        exit 1
+        ;;
+esac
+
+# Check if tsx is available
+if ! command -v tsx &> /dev/null; then
+    echo "Error: tsx is not installed"
+    echo "Run: npm install -g tsx"
+    exit 1
+fi
+
+# Determine the fixer file
+FIXER_FILE="$PROJECT_ROOT/lib/fixer/${FIXER_TYPE}-gated-fixer-v2.ts"
+
+if [[ ! -f "$FIXER_FILE" ]]; then
+    echo "Error: Fixer file not found: $FIXER_FILE"
+    exit 1
+fi
+
+# Run the fixer
+echo "🔧 Running CFN Compilation Error Fixer for $FIXER_TYPE..."
+echo "   File: $FIXER_FILE"
+echo "   Options: $*"
+echo ""
+
+# Set environment for optional SDK
+export CFN_ALLOW_FALLBACK=true
+
+# Execute with tsx
+cd "$PROJECT_ROOT"
+tsx "$FIXER_FILE" "$@"

package/.claude/skills/cfn-compilation-error-fixer/index.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+/**
+ * CFN Compilation Error Fixer - Main Entry Point
+ *
+ * This module provides a Node.js entry point for the compilation error fixer.
+ * It delegates to the appropriate TypeScript implementation based on the error type.
+ */
+
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const errorType = args[0] || 'rust';
+
+// Map error types to fixer files
+const fixerMap = {
+    'rust': 'cerebras-gated-fixer-v2.ts',
+    'typescript': 'typescript-gated-fixer-v2.ts',
+    'ts': 'typescript-gated-fixer-v2.ts'
+};
+
+// Validate error type
+if (!fixerMap[errorType]) {
+    console.error(`❌ Invalid error type: ${errorType}`);
+    console.error('Valid types: rust, typescript (or ts)');
+    process.exit(1);
+}
+
+// Show help
+if (errorType === '--help' || errorType === '-h') {
+    console.log('CFN Compilation Error Fixer');
+    console.log('');
+    console.log('Usage:');
+    console.log('  node index.js [rust|typescript] [options]');
+    console.log('  npm run fix [rust|typescript] [options]');
+    console.log('');
+    console.log('Examples:');
+    console.log('  node index.js rust                    # Fix Rust errors');
+    console.log('  node index.js rust --dry-run         # Dry run for Rust');
+    console.log('  node index.js typescript             # Fix TypeScript errors');
+    console.log('  node index.js ts --verbose           # Verbose TypeScript fixing');
+    process.exit(0);
+}
+
+// Prepare to run the fixer
+const fixerFile = join(__dirname, 'lib', 'fixer', fixerMap[errorType]);
+const fixerArgs = args.slice(1); // Skip the error type argument
+
+// Set environment for optional SDK
+process.env.CFN_ALLOW_FALLBACK = 'true';
+
+// Run the fixer with tsx
+console.log(`🔧 Running CFN Compilation Error Fixer for ${errorType}...`);
+console.log(`   File: ${fixerFile}`);
+console.log(`   Options: ${fixerArgs.join(' ') || 'none'}`);
+console.log('');
+
+const child = spawn('npx', ['tsx', fixerFile, ...fixerArgs], {
+    stdio: 'inherit',
+    cwd: __dirname
+});
+
+// Handle exit
+child.on('exit', (code) => {
+    process.exit(code || 0);
+});
+
+child.on('error', (err) => {
+    console.error('❌ Error running fixer:', err.message);
+    console.error('\nPossible solutions:');
+    console.error('1. Run: npm install');
+    console.error('2. Ensure tsx is installed: npm install -g tsx');
+    console.error('3. Try using the shell script: ./bin/fix-errors.sh');
+    process.exit(1);
+});

package/.claude/skills/cfn-compilation-error-fixer/install.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+set -eu
+
+# CFN Compilation Error Fixer Installation Script
+
+echo "🔧 Installing CFN Compilation Error Fixer..."
+echo "============================================"
+
+# Check Node.js version
+if ! command -v node &> /dev/null; then
+    echo "❌ Error: Node.js is not installed"
+    echo "Please install Node.js >= 18.0.0 from https://nodejs.org/"
+    exit 1
+fi
+
+NODE_VERSION=$(node -v | cut -d'v' -f2)
+REQUIRED_VERSION="18.0.0"
+
+if ! node -e "process.exit(require('semver').gte('$NODE_VERSION', '$REQUIRED_VERSION') ? 0 : 1)" 2>/dev/null; then
+    # Fallback check if semver not available
+    if [[ "$NODE_VERSION" < "18.0.0" ]]; then
+        echo "❌ Error: Node.js version $NODE_VERSION is too old"
+        echo "Please upgrade to Node.js >= 18.0.0"
+        exit 1
+    fi
+fi
+
+echo "✅ Node.js version: $NODE_VERSION"
+
+# Install dependencies
+echo ""
+echo "📦 Installing dependencies..."
+npm install
+
+# Make scripts executable
+echo ""
+echo "🔐 Setting permissions..."
+chmod +x bin/fix-errors.sh
+
+# Check optional dependencies
+echo ""
+echo "🔍 Checking optional dependencies..."
+
+if npm list @cerebras/cerebras_cloud_sdk &> /dev/null; then
+    echo "✅ Cerebras SDK installed - LLM processing enabled"
+else
+    echo "⚠️  Cerebras SDK not installed - fallback mode active"
+    echo "   To enable LLM fixes: npm install @cerebras/cerebras_cloud_sdk"
+fi
+
+# Installation complete
+echo ""
+echo "✅ Installation complete!"
+echo ""
+echo "Quick start:"
+echo "  npm run fix:rust          # Fix Rust errors"
+echo "  npm run fix:ts            # Fix TypeScript errors"
+echo "  npm run fix:rust --dry-run # Preview fixes"
+echo ""
+echo "For more information, see README.md"