Release v1.0.0: Pure Node.js Claude Hooks with Shadow Learning
🚀 Production-ready release of the intelligent hooks system for Claude Code. ## Key Features - Pure Node.js implementation (no Python dependencies) - Shadow learning with pattern recognition and confidence scoring - Auto-configuration via npm postinstall script - Comprehensive Diátaxis documentation framework - End-to-end testing and validation ## Package Distribution - NPM-ready with global CLI binary - Auto-configures hooks during installation - Fail-safe design with graceful degradation - Complete API reference and development docs ## Release Notes - CHANGELOG.md with comprehensive v1.0.0 details - CONTRIBUTING.md with development guidelines - Updated package.json with distribution metadata - Ready for npm registry publication 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
parent
392833187e
commit
50fd0266c9
88
CHANGELOG.md
Normal file
88
CHANGELOG.md
Normal file
@ -0,0 +1,88 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to this project will be documented in this file.
|
||||
|
||||
## [1.0.0] - 2025-01-20
|
||||
|
||||
### ✨ Initial Release
|
||||
|
||||
**🚀 Core Features:**
|
||||
- **Shadow Learning System**: Intelligent pattern recognition that learns from command failures and successes
|
||||
- **Context Monitoring**: Automatic backup triggers based on token usage estimation
|
||||
- **Command Validation**: Real-time prevention of dangerous operations with smart suggestions
|
||||
- **Session Continuity**: Persistent state tracking across Claude sessions with LAST_SESSION.md
|
||||
|
||||
**🏗️ Architecture:**
|
||||
- **Pure Node.js Implementation**: No Python dependencies, full npm ecosystem integration
|
||||
- **Event-Driven Hooks**: UserPromptSubmit, PreToolUse, PostToolUse, Stop hook points
|
||||
- **Auto-Configuration**: Hooks configure themselves during npm install via postinstall script
|
||||
- **Fail-Safe Design**: All components designed to degrade gracefully without blocking Claude
|
||||
|
||||
**📚 Documentation:**
|
||||
- **Diátaxis Framework**: Complete tutorial, how-to guides, reference docs, and explanations
|
||||
- **Bootstrap Installation**: Self-installing prompt for Claude Code integration
|
||||
- **API Reference**: Comprehensive hook development documentation
|
||||
|
||||
**🔧 CLI Tools:**
|
||||
- `claude-hooks status` - System status and session information
|
||||
- `claude-hooks test` - Comprehensive hook validation
|
||||
- `claude-hooks backup` - Manual backup creation
|
||||
- `claude-hooks patterns` - View learned intelligence patterns
|
||||
|
||||
**💡 Intelligence Features:**
|
||||
- **Pattern Matching**: Learns which commands work/fail in your environment
|
||||
- **Confidence Scoring**: Weighs suggestions based on evidence strength
|
||||
- **Context Awareness**: Adapts behavior based on project type and history
|
||||
- **Fuzzy Command Matching**: Handles variations and partial command matches
|
||||
|
||||
**🛡️ Safety Features:**
|
||||
- **Dangerous Command Detection**: Blocks destructive operations automatically
|
||||
- **Path Validation**: Prevents access to system files and path traversal
|
||||
- **Circuit Breaker Pattern**: Auto-disables problematic hooks after failures
|
||||
- **Input Sanitization**: Comprehensive validation of all hook inputs/outputs
|
||||
|
||||
### 🔄 Migration Notes
|
||||
|
||||
This is the initial stable release. Future versions will maintain backward compatibility for:
|
||||
- Hook configuration files
|
||||
- Learned pattern databases
|
||||
- Session state format
|
||||
- CLI command interface
|
||||
|
||||
### 🎯 Installation
|
||||
|
||||
**NPM (Recommended):**
|
||||
```bash
|
||||
npm install -g claude-hooks
|
||||
```
|
||||
|
||||
**Git Clone:**
|
||||
```bash
|
||||
git clone https://git.supported.systems/rsp2k/claude-hooks.git
|
||||
cd claude-hooks
|
||||
npm install
|
||||
npm link
|
||||
```
|
||||
|
||||
### 🏃 Quick Start
|
||||
|
||||
After installation, hooks auto-configure. Test with:
|
||||
```bash
|
||||
claude-hooks test
|
||||
```
|
||||
|
||||
Then restart Claude Code to activate the intelligent assistance.
|
||||
|
||||
### 🤝 Contributing
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and contribution guidelines.
|
||||
|
||||
### 📄 License
|
||||
|
||||
MIT License - see [LICENSE](LICENSE) for details.
|
||||
|
||||
---
|
||||
|
||||
**🎉 Welcome to Claude Code with Intelligence!**
|
||||
|
||||
Your AI assistant now learns from every interaction, prevents common mistakes, and automatically protects your work. The more you use it, the smarter it gets.
|
||||
342
CONTRIBUTING.md
Normal file
342
CONTRIBUTING.md
Normal file
@ -0,0 +1,342 @@
|
||||
# Contributing to Claude Hooks
|
||||
|
||||
Thank you for your interest in contributing to Claude Hooks! This document provides guidelines for contributing to the project.
|
||||
|
||||
## 🚀 Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js 16.0.0 or higher
|
||||
- npm 8.0.0 or higher
|
||||
- Claude Code CLI installed
|
||||
- Git for version control
|
||||
|
||||
### Development Setup
|
||||
|
||||
1. **Fork and clone the repository:**
|
||||
```bash
|
||||
git clone https://git.supported.systems/your-username/claude-hooks.git
|
||||
cd claude-hooks
|
||||
```
|
||||
|
||||
2. **Install dependencies:**
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
3. **Link for local development:**
|
||||
```bash
|
||||
npm link
|
||||
```
|
||||
|
||||
4. **Run tests:**
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
|
||||
5. **Test integration with Claude Code:**
|
||||
```bash
|
||||
claude-hooks test
|
||||
```
|
||||
|
||||
## 🏗️ Project Structure
|
||||
|
||||
```
|
||||
claude-hooks/
|
||||
├── bin/ # CLI executable
|
||||
│ └── claude-hooks.js
|
||||
├── hooks/ # Hook implementations
|
||||
│ ├── context-monitor.js
|
||||
│ ├── command-validator.js
|
||||
│ ├── session-logger.js
|
||||
│ └── session-finalizer.js
|
||||
├── lib/ # Core libraries
|
||||
│ ├── shadow-learner.js
|
||||
│ ├── backup-manager.js
|
||||
│ ├── session-state.js
|
||||
│ └── context-monitor.js
|
||||
├── config/ # Configuration templates
|
||||
├── docs/ # Diátaxis documentation
|
||||
└── tests/ # Test suites
|
||||
```
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### Test Levels
|
||||
|
||||
1. **Unit Tests** - Individual component testing
|
||||
2. **Integration Tests** - Hook pipeline testing
|
||||
3. **End-to-End Tests** - Full Claude Code integration
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# All tests
|
||||
npm test
|
||||
|
||||
# Specific test categories
|
||||
npm run test:unit
|
||||
npm run test:integration
|
||||
npm run test:e2e
|
||||
|
||||
# Coverage report
|
||||
npm run test:coverage
|
||||
```
|
||||
|
||||
### Writing Tests
|
||||
|
||||
Example hook test:
|
||||
```javascript
|
||||
const { testHook } = require('../tests/test-utils');
|
||||
|
||||
describe('CommandValidator', () => {
|
||||
it('should block dangerous commands', async () => {
|
||||
const input = {
|
||||
tool: 'Bash',
|
||||
parameters: { command: 'rm -rf /' }
|
||||
};
|
||||
|
||||
const result = await testHook('command-validator.js', input);
|
||||
|
||||
expect(result.allow).toBe(false);
|
||||
expect(result.message).toContain('dangerous');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## 📝 Code Style
|
||||
|
||||
### JavaScript Standards
|
||||
|
||||
- **ES2020+** syntax
|
||||
- **CommonJS** modules (for Claude Code compatibility)
|
||||
- **JSDoc** comments for public APIs
|
||||
- **Async/await** for asynchronous operations
|
||||
|
||||
### Linting and Formatting
|
||||
|
||||
```bash
|
||||
# Lint code
|
||||
npm run lint
|
||||
|
||||
# Auto-fix linting issues
|
||||
npm run lint:fix
|
||||
|
||||
# Format code
|
||||
npm run format
|
||||
```
|
||||
|
||||
### Example Code Style
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Validates a bash command for safety and provides suggestions
|
||||
* @param {Object} input - Hook input data
|
||||
* @param {string} input.tool - Tool name (should be 'Bash')
|
||||
* @param {Object} input.parameters - Tool parameters
|
||||
* @returns {Promise<Object>} Validation result
|
||||
*/
|
||||
async function validateCommand(input) {
|
||||
const { tool, parameters } = input;
|
||||
|
||||
if (tool !== 'Bash') {
|
||||
return { allow: true };
|
||||
}
|
||||
|
||||
const { command } = parameters;
|
||||
const dangerousPatterns = [
|
||||
/rm\s+-rf\s+\//,
|
||||
/mkfs\./
|
||||
];
|
||||
|
||||
for (const pattern of dangerousPatterns) {
|
||||
if (pattern.test(command)) {
|
||||
return {
|
||||
allow: false,
|
||||
message: '⛔ Command blocked: Dangerous pattern detected'
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
return { allow: true };
|
||||
}
|
||||
```
|
||||
|
||||
## 🎯 Contribution Types
|
||||
|
||||
### 🐛 Bug Reports
|
||||
|
||||
Use the issue template:
|
||||
```markdown
|
||||
**Bug Description:**
|
||||
Brief description of the bug
|
||||
|
||||
**Steps to Reproduce:**
|
||||
1. Step one
|
||||
2. Step two
|
||||
3. Expected vs actual behavior
|
||||
|
||||
**Environment:**
|
||||
- OS: [e.g., macOS 13.0]
|
||||
- Node.js version: [e.g., 18.17.0]
|
||||
- Claude Code version: [e.g., 1.2.3]
|
||||
- claude-hooks version: [e.g., 1.0.0]
|
||||
|
||||
**Additional Context:**
|
||||
Hook logs, error messages, etc.
|
||||
```
|
||||
|
||||
### ✨ Feature Requests
|
||||
|
||||
Include:
|
||||
- **Use case**: Why is this feature needed?
|
||||
- **Proposed solution**: How should it work?
|
||||
- **Alternatives considered**: Other approaches
|
||||
- **Breaking changes**: Any compatibility concerns
|
||||
|
||||
### 🔧 Code Contributions
|
||||
|
||||
#### Hooks Development
|
||||
|
||||
New hooks should:
|
||||
- Follow the [Hook API Reference](docs/reference/hook-api.md)
|
||||
- Include comprehensive tests
|
||||
- Handle errors gracefully
|
||||
- Execute within performance requirements (<50ms for PreToolUse)
|
||||
|
||||
#### Shadow Learner Enhancements
|
||||
|
||||
When extending the shadow learner:
|
||||
- Maintain backward compatibility with existing pattern databases
|
||||
- Include confidence scoring for new pattern types
|
||||
- Document learning algorithms clearly
|
||||
- Test with various failure scenarios
|
||||
|
||||
#### Documentation Improvements
|
||||
|
||||
Follow the [Diátaxis framework](https://diataxis.fr/):
|
||||
- **Tutorials**: Learning-oriented, hands-on guidance
|
||||
- **How-to guides**: Goal-oriented, practical steps
|
||||
- **Reference**: Information-oriented, comprehensive details
|
||||
- **Explanation**: Understanding-oriented, theoretical background
|
||||
|
||||
## 🔄 Pull Request Process
|
||||
|
||||
### Before Submitting
|
||||
|
||||
1. **Test thoroughly:**
|
||||
```bash
|
||||
npm test
|
||||
npm run lint
|
||||
claude-hooks test
|
||||
```
|
||||
|
||||
2. **Update documentation** if needed
|
||||
3. **Add changelog entry** for user-facing changes
|
||||
4. **Ensure backward compatibility** or document breaking changes
|
||||
|
||||
### PR Guidelines
|
||||
|
||||
1. **Clear title**: Describe what the PR does
|
||||
2. **Detailed description**:
|
||||
- What problem does this solve?
|
||||
- How does the solution work?
|
||||
- Any breaking changes or migration notes?
|
||||
3. **Link related issues**
|
||||
4. **Request specific reviewers** if needed
|
||||
|
||||
### Example PR Description
|
||||
|
||||
```markdown
|
||||
## Summary
|
||||
Add support for Python virtual environment detection in command validation
|
||||
|
||||
## Changes
|
||||
- Extend shadow learner to detect venv/conda environments
|
||||
- Update command validator to suggest environment-specific alternatives
|
||||
- Add tests for virtual environment scenarios
|
||||
|
||||
## Testing
|
||||
- [ ] Unit tests pass
|
||||
- [ ] Integration tests with venv scenarios
|
||||
- [ ] Manual testing in conda environment
|
||||
|
||||
## Breaking Changes
|
||||
None - fully backward compatible
|
||||
|
||||
Fixes #123
|
||||
```
|
||||
|
||||
## 🎯 Development Guidelines
|
||||
|
||||
### Hook Development
|
||||
|
||||
1. **Error Handling**: Always fail safely
|
||||
```javascript
|
||||
try {
|
||||
// Hook logic
|
||||
return { allow: true, message: 'Success' };
|
||||
} catch (error) {
|
||||
console.error('Hook error:', error);
|
||||
return { allow: true }; // Fail open
|
||||
}
|
||||
```
|
||||
|
||||
2. **Performance**: Keep hooks fast
|
||||
```javascript
|
||||
const MAX_EXECUTION_TIME = 50; // ms for PreToolUse
|
||||
```
|
||||
|
||||
3. **Logging**: Use structured logging
|
||||
```javascript
|
||||
console.log(JSON.stringify({
|
||||
timestamp: new Date().toISOString(),
|
||||
hook: 'command-validator',
|
||||
action: 'blocked-command',
|
||||
command: sanitizeForLog(command)
|
||||
}));
|
||||
```
|
||||
|
||||
### Shadow Learner Extensions
|
||||
|
||||
1. **Pattern Validation**: Ensure patterns are meaningful
|
||||
```javascript
|
||||
function validatePattern(pattern) {
|
||||
return pattern.confidence > 0.1 &&
|
||||
pattern.evidence_count > 2 &&
|
||||
pattern.last_seen > Date.now() - 30 * 24 * 60 * 60 * 1000;
|
||||
}
|
||||
```
|
||||
|
||||
2. **Storage Efficiency**: Keep databases compact
|
||||
```javascript
|
||||
// Prune old patterns periodically
|
||||
function pruneOldPatterns(db) {
|
||||
const cutoff = Date.now() - 90 * 24 * 60 * 60 * 1000; // 90 days
|
||||
return db.filter(pattern => pattern.last_seen > cutoff);
|
||||
}
|
||||
```
|
||||
|
||||
## 🌟 Recognition
|
||||
|
||||
Contributors are recognized in:
|
||||
- **README.md** contributors section
|
||||
- **CHANGELOG.md** for significant contributions
|
||||
- **GitHub releases** with contributor highlights
|
||||
|
||||
## 📞 Getting Help
|
||||
|
||||
- **Questions**: Open a GitHub discussion
|
||||
- **Bug reports**: Create an issue with the bug template
|
||||
- **Development help**: Tag @maintainers in discussions
|
||||
- **Real-time chat**: Join our Discord server (link in README)
|
||||
|
||||
## 🏆 Code of Conduct
|
||||
|
||||
This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). Please read and follow these guidelines to ensure a welcoming environment for all contributors.
|
||||
|
||||
---
|
||||
|
||||
**Thank you for contributing to Claude Hooks!** 🎉
|
||||
|
||||
Your contributions help make AI assistance more intelligent, reliable, and useful for developers worldwide.
|
||||
@ -26,7 +26,10 @@
|
||||
"lib/",
|
||||
"config/",
|
||||
"docs/",
|
||||
"README.md"
|
||||
"README.md",
|
||||
"CHANGELOG.md",
|
||||
"CONTRIBUTING.md",
|
||||
"LICENSE"
|
||||
],
|
||||
"scripts": {
|
||||
"postinstall": "node bin/claude-hooks.js init --auto-setup",
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user