ccjk 14.1.10 → 14.2.0

package/dist/templates/common/error-prevention.md

@@ -0,0 +1,267 @@
+# CCJK Error Prevention System
+
+**IMPORTANT**: This project uses the CCJK Error Prevention System to automatically prevent and fix common Claude Code CLI errors.
+
+---
+
+## 🛡️ Automatic Error Prevention
+
+All file operations and commands are automatically protected by CCJK's intelligent error prevention system.
+
+### What It Does
+
+The Error Prevention System operates in 5 layers:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│              CCJK Error Prevention System                        │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  Layer 1: Pre-Execution Validation                               │
+│    ├─ Parameter format validation                                │
+│    ├─ Path validity checks                                       │
+│    ├─ Permission verification                                    │
+│    └─ Command existence validation                               │
+│                                                                  │
+│  Layer 2: Intelligent Wrappers                                   │
+│    ├─ Smart Write: Handles existing files automatically          │
+│    ├─ Smart Bash: Validates and retries commands                 │
+│    ├─ Smart Path: Resolves cross-platform paths                  │
+│    └─ Smart Edit: Detects content changes before editing         │
+│                                                                  │
+│  Layer 3: Auto-Recovery                                          │
+│    ├─ Retry with exponential backoff                             │
+│    ├─ Automatic error correction                                 │
+│    ├─ Rollback support                                           │
+│    └─ Fallback mechanisms                                        │
+│                                                                  │
+│  Layer 4: Real-time Monitoring                                   │
+│    ├─ Error detection and classification                         │
+│    ├─ Pattern analysis                                           │
+│    └─ Alert system                                               │
+│                                                                  │
+│  Layer 5: Learning System                                        │
+│    ├─ Error history tracking                                     │
+│    └─ Solution database                                          │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 📋 Errors That Are Automatically Prevented
+
+### 1. Error Writing File
+
+**Causes**: File already exists, permission denied, path errors
+
+**CCJK Auto-Fix**:
+- ✅ Checks if file exists before writing
+- ✅ Automatically backs up existing files
+- ✅ Uses Edit instead of Write when file exists
+- ✅ Creates missing directories automatically
+- ✅ Retries on transient failures
+
+### 2. Invalid Tool Parameters
+
+**Causes**: Wrong parameter format, missing required parameters, type mismatch
+
+**CCJK Auto-Fix**:
+- ✅ Validates parameter format before execution
+- ✅ Checks for unclosed quotes
+- ✅ Validates file paths
+- ✅ Provides specific error messages
+
+### 3. Bash Command Failures (Exit Code 1)
+
+**Causes**: Command not found, syntax errors, missing environment variables
+
+**CCJK Auto-Fix**:
+- ✅ Validates command exists before execution
+- ✅ Checks parameter format
+- ✅ Sets up environment automatically
+- ✅ Retries on failures with exponential backoff
+- ✅ Suggests alternative commands
+
+### 4. Path Resolution Issues
+
+**Causes**: Relative path errors, symlinks, cross-platform differences
+
+**CCJK Auto-Fix**:
+- ✅ Handles ~ (home directory)
+- ✅ Expands environment variables
+- ✅ Resolves symlinks
+- ✅ Cross-platform path normalization
+- ✅ Provides path fix suggestions
+
+### 5. Permission Denied Errors
+
+**Causes**: File permissions, directory permissions, read-only filesystem
+
+**CCJK Auto-Fix**:
+- ✅ Checks permissions before operations
+- ✅ Attempts to fix script permissions (chmod +x)
+- ✅ Provides specific permission error messages
+- ✅ Suggests appropriate fixes
+
+---
+
+## 🚀 Best Practices
+
+### When Writing Files
+
+**❌ Don't worry about**:
+- File already existing → CCJK handles it
+- Creating directories → CCJK does it automatically
+- Backing up files → CCJK backs up automatically
+- Content validation → CCJK checks before writing
+
+**✅ Just write**:
+- CCJK will detect if file exists
+- CCJK will use Edit tool if appropriate
+- CCJK will create directories if needed
+- CCJK will retry if write fails
+
+### When Running Commands
+
+**❌ Don't worry about**:
+- Command not existing → CCJK checks first
+- Parameter format → CCJK validates
+- Environment setup → CCJK sets up automatically
+- Command failing → CCJK retries with auto-fix
+
+**✅ Just run**:
+- CCJK will validate command exists
+- CCJK will check parameters
+- CCJK will handle dangerous command warnings
+- CCJK will retry on failures
+
+### When Reading Files
+
+**❌ Don't worry about**:
+- Path resolution → CCJK resolves paths
+- File not found → CCJK provides clear error
+- Permission issues → CCJK checks permissions
+
+**✅ Just read**:
+- CCJK will resolve relative paths
+- CCJK will handle symlinks
+- CCJK will provide helpful error messages
+
+---
+
+## 💡 Error Recovery Flow
+
+When an error occurs, CCJK follows this process:
+
+```
+1. Detect → Classify error type
+2. Analyze → Determine if retryable
+3. Auto-fix → Apply automatic correction if possible
+4. Retry → Retry with exponential backoff
+5. Fallback → Suggest alternative approach
+6. Report → Provide detailed error and suggestion
+```
+
+---
+
+## 🔧 Debugging
+
+### Enable Debug Logging
+
+```bash
+# Enable error prevention debug output
+export CCJK_ERROR_PREVENTION_DEBUG=1
+
+# Or enable all CCJK debug output
+export CCJK_DEBUG=1
+```
+
+### View Error Statistics
+
+```typescript
+import { getMiddleware } from 'ccjk/error-prevention'
+
+const middleware = getMiddleware()
+const errorStats = middleware.getErrorStats()
+const fixStats = middleware.getFixStats()
+
+console.log('Error Stats:', errorStats)
+console.log('Fix Stats:', fixStats)
+```
+
+---
+
+## 📊 Expected Impact
+
+| Error Type | Before CCJK | After CCJK | Reduction |
+|------------|-------------|------------|-----------|
+| Error writing file | ⭐⭐⭐⭐⭐ | ⭐ | **80%** |
+| Invalid tool parameters | ⭐⭐⭐⭐ | ⭐ | **75%** |
+| Bash command failures | ⭐⭐⭐⭐ | ⭐ | **70%** |
+| Path resolution issues | ⭐⭐⭐ | ⭐ | **85%** |
+| Permission denied | ⭐⭐⭐ | ⭐ | **90%** |
+
+---
+
+## 🎯 Tips
+
+1. **Trust CCJK's automatic handling** - Let the system prevent errors
+2. **Check console for CCJK messages** - Look for `[CCJK ErrorPrevention]` prefix
+3. **Review suggestions when errors occur** - CCJK provides specific fix suggestions
+4. **Report persistent errors** - Help improve the system
+
+---
+
+## 📖 API Reference
+
+```typescript
+import {
+  getMiddleware,
+  SmartWriteTool,
+  SmartBashTool,
+  SmartPathResolver,
+} from 'ccjk/error-prevention'
+
+// Use middleware (recommended)
+const middleware = getMiddleware()
+
+// Write files
+const writeResult = await middleware.interceptWrite(path, content)
+
+// Execute commands
+const bashResult = await middleware.interceptBash(command, options)
+
+// Read files
+const readResult = await middleware.interceptRead(path)
+
+// Edit files
+const editResult = await middleware.interceptEdit(path, oldString, newString)
+
+// Get path info
+const pathInfo = await middleware.getPathInfo(path)
+
+// Get statistics
+const errors = middleware.getErrorStats()
+const fixes = middleware.getFixStats()
+```
+
+---
+
+## 🎉 Summary
+
+**Before CCJK Error Prevention**:
+- ❌ Frequent errors
+- ❌ Manual debugging
+- ❌ Time wasted
+- ❌ Frustration
+
+**After CCJK Error Prevention**:
+- ✅ Automatic prevention
+- ✅ Intelligent fixes
+- ✅ Efficient development
+- ✅ Peace of mind
+
+---
+
+**Let CCJK handle the errors, focus on your code! 🚀**

package/dist/templates/common/karpathy-baseline.md

@@ -0,0 +1,83 @@
+# Coding Discipline Baseline
+
+> Default behavior for all coding tasks in this project, unless the user
+> explicitly says otherwise. Inspired by Andrej Karpathy's observations on
+> common LLM coding failure modes.
+
+These rules apply to **every** task. Style guides (Linus / Carmack / DHH …)
+layer on top — they change voice, not discipline.
+
+---
+
+## 1. Think before coding
+
+Surface ambiguity. Don't pick silently.
+
+- If the request has two reasonable interpretations, present both and ask.
+- If a constraint is unclear (target file, scope, behavior), ask before coding.
+- If you'd push back on a senior engineer ("this seems unnecessary"), do.
+- Prefer clarifying questions before edits over rework after.
+
+## 2. Simplicity first
+
+Minimum code that meets the stated request. Nothing speculative.
+
+- No unrequested features, options, flags, or config knobs.
+- No abstractions for single-use code. No interfaces with one implementation.
+- No error handling for impossible scenarios.
+- If 200 lines could be 50, rewrite.
+
+Litmus test: a senior engineer reviewing the diff should not think "why all this?"
+
+## 3. Surgical changes
+
+Touch only what the task requires.
+
+- Don't reformat or "improve" code adjacent to your edit.
+- Don't refactor working code unless that *is* the task.
+- Match existing style/naming/imports — don't introduce a new convention.
+- For orphans created by your own change (now-unused imports, variables, helpers): remove them. For pre-existing dead code: leave it, mention it.
+
+Litmus test: every changed line should trace directly to the user's request.
+
+## 4. Goal-driven execution
+
+Convert tasks into verifiable goals. Loop until the goal is met — don't ask
+the user to re-run something you can verify yourself.
+
+| Vague request | Verifiable goal |
+|---|---|
+| "Add validation" | Write a failing test for invalid input, then make it pass |
+| "Fix the bug" | Write a reproducing test, then make it pass |
+| "Refactor X" | Confirm the same tests pass before and after |
+| "Make it work" | Define what "work" means with a command + expected output |
+
+For multi-step tasks, share a brief plan with verification per step before
+starting. Strong goals enable independent looping. Weak goals ("make it
+nice") force back-and-forth.
+
+---
+
+## Project-specific rules
+
+These extend the baseline; they don't replace it.
+
+- **Verification commands:** `pnpm typecheck`, `pnpm lint`, `pnpm test:run`,
+  `pnpm test:release` (curated subset). For Codex/Claude integration paths,
+  smoke test with `echo '<option>' | node dist/cli.mjs`.
+- **Generated rule files:** `CLAUDE.md`, `clavue.md`, `AGENTS.md` are
+  rewritten by Clavue `/init`. Put durable guidance in
+  `docs/CLAUDE-NOTES.md`.
+- **Anti-aggression:** ccjk complements Claude Code; do not auto-run things
+  in Claude's runtime. Skills run only on explicit invocation. Don't add
+  background hooks that fire on every tool call.
+- **Workspace ownership:** ccjk config lives at `~/.ccjk/`, separate from
+  `~/.claude/` and `~/.codex/`. Don't mix them.
+
+---
+
+## When to skip this baseline
+
+- Trivial fixes (typo, one-liner): use judgment, don't over-process.
+- The user explicitly says "just do it" / "no questions": skip clarification, but keep simplicity + surgical edits.
+- Emergencies (build broken, prod down): goal is restore-first, then write the regression test.