diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 71b50d8..e61d06d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,12 +6,12 @@ }, "metadata": { "description": "Project management plugins with Gitea and NetBox integrations", - "version": "2.2.0" + "version": "2.3.0" }, "plugins": [ { "name": "projman", - "version": "2.2.0", + "version": "2.3.0", "description": "Sprint planning and project management with Gitea integration", "source": "./plugins/projman", "author": { @@ -23,6 +23,36 @@ "mcpServers": ["gitea"], "integrationFile": "claude-md-integration.md" }, + { + "name": "doc-guardian", + "version": "1.0.0", + "description": "Automatic documentation drift detection and synchronization", + "source": "./plugins/doc-guardian", + "author": { + "name": "Leo Miranda", + "email": "leobmiranda@gmail.com" + }, + "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/doc-guardian/README.md", + "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git", + "mcpServers": [], + "integrationFile": "claude-md-integration.md", + "hooks": ["PostToolUse", "Stop"] + }, + { + "name": "code-sentinel", + "version": "1.0.0", + "description": "Security scanning and code refactoring tools", + "source": "./plugins/code-sentinel", + "author": { + "name": "Leo Miranda", + "email": "leobmiranda@gmail.com" + }, + "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/code-sentinel/README.md", + "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git", + "mcpServers": [], + "integrationFile": "claude-md-integration.md", + "hooks": ["PreToolUse"] + }, { "name": "project-hygiene", "version": "0.1.0", @@ -73,7 +103,9 @@ "netbox": "cmdb-assistant" }, "hookMapping": { - "PostToolUse:Write|Edit": "project-hygiene" + "PostToolUse:Write|Edit": "project-hygiene", + "PostToolUse:Write|Edit|MultiEdit": "doc-guardian", + "PreToolUse:Write|Edit|MultiEdit": "code-sentinel" } } } diff --git a/CHANGELOG.md b/CHANGELOG.md index 184464b..7600b71 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,35 @@ All notable changes to support-claude-mktplace will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). +## [2.3.0] - 2026-01-20 + +### Added + +#### New Plugins +- **doc-guardian** v1.0.0 - Documentation lifecycle management + - `/doc-audit` command for full project documentation drift analysis + - `/doc-sync` command to batch apply pending documentation updates + - PostToolUse hook for automatic drift detection + - Stop hook reminder for pending updates + - doc-analyzer agent for cross-reference analysis + - doc-patterns skill for documentation structure knowledge + +- **code-sentinel** v1.0.0 - Security scanning and refactoring + - `/security-scan` command for comprehensive security audit + - `/refactor` command to apply refactoring patterns + - `/refactor-dry` command to preview refactoring opportunities + - PreToolUse hook for real-time security scanning + - security-reviewer agent for vulnerability analysis + - refactor-advisor agent for code structure improvements + - security-patterns skill for vulnerability detection rules + +#### projman Enhancements +- `/test-gen` command - Generate unit, integration, and e2e tests for specified code + +### Changed +- Marketplace version bumped to 2.3.0 +- projman version bumped to 2.3.0 + ## [2.2.0] - 2026-01-20 ### Added diff --git a/CLAUDE.md b/CLAUDE.md index eaef7a1..09b8b55 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,14 +5,16 @@ This file provides guidance to Claude Code when working with code in this reposi ## Project Overview **Repository:** support-claude-mktplace -**Version:** 2.2.0 +**Version:** 2.3.0 **Status:** Production Ready A Claude Code plugin marketplace containing: | Plugin | Description | Version | |--------|-------------|---------| -| `projman` | Sprint planning and project management with Gitea integration | 2.2.0 | +| `projman` | Sprint planning and project management with Gitea integration | 2.3.0 | +| `doc-guardian` | Automatic documentation drift detection and synchronization | 1.0.0 | +| `code-sentinel` | Security scanning and code refactoring tools | 1.0.0 | | `claude-config-maintainer` | CLAUDE.md optimization and maintenance | 1.0.0 | | `cmdb-assistant` | NetBox CMDB integration for infrastructure management | 1.0.0 | | `project-hygiene` | Post-task cleanup automation via hooks | 0.1.0 | @@ -42,14 +44,26 @@ support-claude-mktplace/ │ │ ├── .claude-plugin/plugin.json │ │ ├── .mcp.json │ │ ├── mcp-servers/gitea/ # Bundled MCP server -│ │ ├── commands/ # 8 commands +│ │ ├── commands/ # 9 commands │ │ │ ├── sprint-plan.md, sprint-start.md, sprint-status.md │ │ │ ├── sprint-close.md, labels-sync.md, initial-setup.md -│ │ │ └── review.md, test-check.md +│ │ │ └── review.md, test-check.md, test-gen.md │ │ ├── agents/ # 4 agents │ │ │ ├── planner.md, orchestrator.md, executor.md │ │ │ └── code-reviewer.md │ │ └── skills/label-taxonomy/ +│ ├── doc-guardian/ # Documentation drift detection +│ │ ├── .claude-plugin/plugin.json +│ │ ├── hooks/hooks.json # PostToolUse, Stop hooks +│ │ ├── commands/ # doc-audit.md, doc-sync.md +│ │ ├── agents/ # doc-analyzer.md +│ │ └── skills/doc-patterns/ +│ ├── code-sentinel/ # Security scanning & refactoring +│ │ ├── .claude-plugin/plugin.json +│ │ ├── hooks/hooks.json # PreToolUse hook +│ │ ├── commands/ # security-scan.md, refactor.md, refactor-dry.md +│ │ ├── agents/ # security-reviewer.md, refactor-advisor.md +│ │ └── skills/security-patterns/ │ ├── claude-config-maintainer/ │ ├── cmdb-assistant/ │ └── project-hygiene/ diff --git a/README.md b/README.md index bde7dfb..906f82e 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Claude Code Marketplace - v2.2.0 +# Claude Code Marketplace - v2.3.0 A collection of Claude Code plugins for project management, infrastructure automation, and development workflows. @@ -17,7 +17,7 @@ AI-guided sprint planning with full Gitea integration. Transforms a proven 15-sp - Branch-aware security (development/staging/production) - Pre-sprint-close code quality review and test verification -**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/initial-setup`, `/review`, `/test-check` +**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/initial-setup`, `/review`, `/test-check`, `/test-gen` ### [claude-config-maintainer](./plugins/claude-config-maintainer/README.md) **CLAUDE.md Optimization and Maintenance** @@ -53,6 +53,28 @@ Hook-based cleanup that runs after Claude completes work. - Identifies orphaned supporting files - Configurable via `.hygiene.json` +### [doc-guardian](./plugins/doc-guardian/README.md) +**Documentation Lifecycle Management** + +Automatic documentation drift detection and synchronization. Eliminates manual doc update cycles. + +- PostToolUse hook detects when code changes affect documentation +- Stop hook reminds of pending updates before session ends +- Batched updates in single commit + +**Commands:** `/doc-audit`, `/doc-sync` + +### [code-sentinel](./plugins/code-sentinel/README.md) +**Security Scanning & Refactoring** + +Security vulnerability detection and code refactoring tools. + +- PreToolUse hook catches security issues before code is written +- Pattern library: SQL injection, XSS, command injection, hardcoded secrets +- Refactoring patterns: extract method, simplify conditional, modernize syntax + +**Commands:** `/security-scan`, `/refactor`, `/refactor-dry` + ## MCP Servers MCP servers are **bundled inside each plugin** that needs them. This ensures plugins work when cached by Claude Code. @@ -204,7 +226,9 @@ support-claude-mktplace/ │ │ ├── commands/ │ │ └── agents/ │ ├── projman-pmo/ # PMO coordination plugin (planned) -│ └── project-hygiene/ # Cleanup automation plugin +│ ├── project-hygiene/ # Cleanup automation plugin +│ ├── doc-guardian/ # Documentation drift detection +│ └── code-sentinel/ # Security scanning & refactoring ├── docs/ # Reference documentation │ ├── CANONICAL-PATHS.md # Single source of truth for paths │ └── references/ diff --git a/docs/CANONICAL-PATHS.md b/docs/CANONICAL-PATHS.md index 3ce5994..2465479 100644 --- a/docs/CANONICAL-PATHS.md +++ b/docs/CANONICAL-PATHS.md @@ -29,8 +29,21 @@ support-claude-mktplace/ │ │ ├── agents/ │ │ ├── skills/ │ │ └── claude-md-integration.md # CLAUDE.md integration snippet +│ ├── doc-guardian/ # Documentation drift detection +│ │ ├── .claude-plugin/ +│ │ ├── hooks/ # PostToolUse, Stop hooks +│ │ ├── commands/ +│ │ ├── agents/ +│ │ ├── skills/ +│ │ └── claude-md-integration.md +│ ├── code-sentinel/ # Security scanning & refactoring +│ │ ├── .claude-plugin/ +│ │ ├── hooks/ # PreToolUse hook +│ │ ├── commands/ +│ │ ├── agents/ +│ │ ├── skills/ +│ │ └── claude-md-integration.md │ ├── projman-pmo/ -│ ├── project-hygiene/ │ ├── cmdb-assistant/ │ │ ├── .claude-plugin/ │ │ ├── mcp-servers/ # MCP servers bundled IN plugin diff --git a/plugins/code-sentinel/.claude-plugin/plugin.json b/plugins/code-sentinel/.claude-plugin/plugin.json new file mode 100644 index 0000000..4c2c726 --- /dev/null +++ b/plugins/code-sentinel/.claude-plugin/plugin.json @@ -0,0 +1,13 @@ +{ + "name": "code-sentinel", + "description": "Security scanning and code refactoring tools", + "version": "1.0.0", + "author": { + "name": "Leo Miranda", + "email": "leobmiranda@gmail.com" + }, + "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/code-sentinel/README.md", + "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git", + "license": "MIT", + "keywords": ["security", "refactoring", "code-quality", "static-analysis", "hooks"] +} diff --git a/plugins/code-sentinel/README.md b/plugins/code-sentinel/README.md new file mode 100644 index 0000000..882adc4 --- /dev/null +++ b/plugins/code-sentinel/README.md @@ -0,0 +1,47 @@ +# code-sentinel + +Security scanning and code refactoring tools for Claude Code projects. + +## Features + +### Security Scanning +- **PreToolUse Hook**: Catches vulnerabilities BEFORE code is written +- **Full Audit**: `/security-scan` for comprehensive project review +- **Pattern Detection**: SQL injection, XSS, command injection, secrets, and more + +### Refactoring +- **Pattern Library**: Extract method, simplify conditionals, modernize syntax +- **Safe Transforms**: Preview changes before applying +- **Reference Updates**: Automatically updates all call sites + +## Commands + +| Command | Description | +|---------|-------------| +| `/security-scan` | Full project security audit | +| `/refactor ` | Apply refactoring with pattern | +| `/refactor-dry ` | Preview opportunities without changes | + +## Hooks + +- **PreToolUse (Write\|Edit)**: Scans code for security patterns before writing + +## Security Patterns Detected + +| Category | Examples | +|----------|----------| +| Injection | SQL, Command, Code (eval), XSS | +| Secrets | Hardcoded API keys, passwords | +| Deserialization | Pickle, unsafe YAML | +| Path Traversal | Unsanitized file paths | + +## Installation + +```bash +/plugin marketplace add https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git +/plugin install code-sentinel +``` + +## Integration + +See claude-md-integration.md for CLAUDE.md additions. diff --git a/plugins/code-sentinel/agents/refactor-advisor.md b/plugins/code-sentinel/agents/refactor-advisor.md new file mode 100644 index 0000000..24e6f7c --- /dev/null +++ b/plugins/code-sentinel/agents/refactor-advisor.md @@ -0,0 +1,48 @@ +--- +description: Code structure and refactoring specialist +--- + +# Refactor Advisor Agent + +You are a software architect specializing in code quality, design patterns, and refactoring. + +## Expertise + +- Martin Fowler's refactoring catalog +- SOLID principles +- Design patterns (GoF, enterprise, functional) +- Code smells detection +- Cyclomatic complexity analysis +- Technical debt assessment + +## Analysis Approach + +When analyzing code: + +1. **Identify Code Smells** + - Long methods (>20 lines) + - Large classes (>200 lines) + - Long parameter lists (>3 params) + - Duplicate code + - Feature envy + - Data clumps + +2. **Assess Structure** + - Single responsibility adherence + - Coupling between modules + - Cohesion within modules + - Abstraction levels + +3. **Recommend Refactorings** + - Match smells to appropriate refactorings + - Consider dependencies and side effects + - Prioritize by impact and risk + - Provide step-by-step approach + +## Output Style + +Be practical: +- Focus on high-impact improvements +- Explain the "why" behind recommendations +- Provide concrete before/after examples +- Consider testing implications diff --git a/plugins/code-sentinel/agents/security-reviewer.md b/plugins/code-sentinel/agents/security-reviewer.md new file mode 100644 index 0000000..47e350a --- /dev/null +++ b/plugins/code-sentinel/agents/security-reviewer.md @@ -0,0 +1,50 @@ +--- +description: Security-focused code review agent +--- + +# Security Reviewer Agent + +You are a security engineer specializing in application security and secure coding practices. + +## Expertise + +- OWASP Top 10 vulnerabilities +- Language-specific security pitfalls (Python, JavaScript, Go, etc.) +- Authentication and authorization flaws +- Cryptographic misuse +- Input validation and output encoding +- Secure configuration + +## Review Approach + +When reviewing code: + +1. **Identify Trust Boundaries** + - Where does user input enter? + - Where does data leave the system? + - What operations are privileged? + +2. **Trace Data Flow** + - Follow user input through the code + - Check for sanitization at each boundary + - Verify output encoding + +3. **Check Security Controls** + - Authentication present where needed? + - Authorization checked before actions? + - Secrets properly managed? + - Errors handled without leaking info? + +4. **Language-Specific Checks** + Python: eval, pickle, yaml.load, subprocess + JavaScript: innerHTML, eval, prototype pollution + SQL: parameterized queries, ORM usage + Shell: quoting, input validation + +## Output Style + +Be specific and actionable: +- Quote the vulnerable line +- Explain the attack vector +- Provide the secure alternative +- Rate severity (Critical/High/Medium/Low) diff --git a/plugins/code-sentinel/claude-md-integration.md b/plugins/code-sentinel/claude-md-integration.md new file mode 100644 index 0000000..88d11ba --- /dev/null +++ b/plugins/code-sentinel/claude-md-integration.md @@ -0,0 +1,26 @@ +# Code Sentinel Integration + +Add to your project's CLAUDE.md: + +## Security & Code Quality + +This project uses code-sentinel for security scanning and refactoring. + +### Automatic Security Checks +PreToolUse hooks scan all code changes for: +- SQL/Command/Code injection +- XSS vulnerabilities +- Hardcoded secrets +- Unsafe deserialization + +Critical issues are blocked. Warnings are noted but allowed. + +### Commands +- `/security-scan` - Full project security audit +- `/refactor ` - Apply refactoring pattern +- `/refactor-dry ` - Preview refactoring opportunities + +### Severity Levels +- 🔴 Critical: Must fix immediately +- 🟠 High: Fix before release +- 🟡 Medium: Improve when possible diff --git a/plugins/code-sentinel/commands/refactor-dry.md b/plugins/code-sentinel/commands/refactor-dry.md new file mode 100644 index 0000000..720923a --- /dev/null +++ b/plugins/code-sentinel/commands/refactor-dry.md @@ -0,0 +1,57 @@ +--- +description: Preview refactoring changes without applying them +--- + +# Refactor Dry Run + +Analyze and preview refactoring opportunities without making changes. + +## Usage +``` +/refactor-dry [--all] +``` + +**Target:** File path, function name, or "." for current file +**--all:** Show all opportunities, not just recommended + +## Process + +1. **Scan Target** + Analyze code for refactoring opportunities. + +2. **Score Opportunities** + Each opportunity rated by: + - Impact (how much it improves code) + - Risk (likelihood of breaking something) + - Effort (complexity of the refactoring) + +3. **Output** +``` +## Refactoring Opportunities: src/handlers.py + +### Recommended (High Impact, Low Risk) + +1. **extract-method** at lines 45-67 + - Extract order validation logic + - Impact: High (reduces complexity from 12 to 4) + - Risk: Low (pure function, no side effects) + - Run: `/refactor src/handlers.py:45 --pattern=extract-method` + +2. **use-dataclass** for OrderInput class + - Convert to dataclass with validation + - Impact: Medium (reduces boilerplate) + - Risk: Low + - Run: `/refactor src/models.py:OrderInput --pattern=use-dataclass` + +### Optional (Consider Later) + +3. **use-fstring** at 12 locations + - Modernize string formatting + - Impact: Low (readability only) + - Risk: None + +### Summary +- 2 recommended refactorings +- 1 optional improvement +- Estimated complexity reduction: 35% +``` diff --git a/plugins/code-sentinel/commands/refactor.md b/plugins/code-sentinel/commands/refactor.md new file mode 100644 index 0000000..095617c --- /dev/null +++ b/plugins/code-sentinel/commands/refactor.md @@ -0,0 +1,81 @@ +--- +description: Apply refactoring patterns to improve code structure and maintainability +--- + +# Refactor + +Apply refactoring transformations to specified code. + +## Usage +``` +/refactor [--pattern=] +``` + +**Target:** File path, function name, or "." for current context +**Pattern:** Specific refactoring pattern (optional) + +## Available Patterns + +### Structure +| Pattern | Description | +|---------|-------------| +| `extract-method` | Extract code block into named function | +| `extract-class` | Move related methods to new class | +| `inline` | Inline trivial function/variable | +| `rename` | Rename with all references updated | +| `move` | Move function/class to different module | + +### Simplification +| Pattern | Description | +|---------|-------------| +| `simplify-conditional` | Flatten nested if/else | +| `remove-dead-code` | Delete unreachable code | +| `consolidate-duplicate` | Merge duplicate code blocks | +| `decompose-conditional` | Break complex conditions into named parts | + +### Modernization +| Pattern | Description | +|---------|-------------| +| `use-comprehension` | Convert loops to list/dict comprehensions | +| `use-pathlib` | Replace os.path with pathlib | +| `use-fstring` | Convert .format() to f-strings | +| `use-typing` | Add type hints | +| `use-dataclass` | Convert class to dataclass | + +## Process + +1. **Analyze Target** + - Parse code structure + - Identify refactoring opportunities + - Check for side effects and dependencies + +2. **Propose Changes** + - Show before/after diff + - Explain the improvement + - List affected files/references + +3. **Apply (with confirmation)** + - Make changes + - Update all references + - Run existing tests if available + +4. **Output** +``` +## Refactoring: extract-method + +### Target +src/handlers.py:create_order (lines 45-89) + +### Changes +- Extracted validation logic → validate_order_input() +- Extracted pricing logic → calculate_order_total() +- Original function now 15 lines (was 44) + +### Files Modified +- src/handlers.py +- tests/test_handlers.py (updated calls) + +### Metrics +- Cyclomatic complexity: 12 → 4 +- Function length: 44 → 15 lines +``` diff --git a/plugins/code-sentinel/commands/security-scan.md b/plugins/code-sentinel/commands/security-scan.md new file mode 100644 index 0000000..f4a9571 --- /dev/null +++ b/plugins/code-sentinel/commands/security-scan.md @@ -0,0 +1,64 @@ +--- +description: Full security audit of codebase - scans all files for vulnerability patterns +--- + +# Security Scan + +Comprehensive security audit of the project. + +## Process + +1. **File Discovery** + Scan all code files: .py, .js, .ts, .jsx, .tsx, .go, .rs, .java, .rb, .php, .sh + +2. **Pattern Detection** + + ### Critical Vulnerabilities + | Pattern | Risk | Detection | + |---------|------|-----------| + | SQL Injection | High | String concat in SQL queries | + | Command Injection | High | shell=True, os.system with vars | + | XSS | High | innerHTML with user input | + | Code Injection | Critical | eval/exec with external input | + | Deserialization | Critical | pickle.loads, yaml.load unsafe | + | Path Traversal | High | File ops without sanitization | + | Hardcoded Secrets | High | API keys, passwords in code | + | SSRF | Medium | URL from user input in requests | + + ### Code Quality Issues + | Pattern | Risk | Detection | + |---------|------|-----------| + | Broad Exceptions | Low | `except:` or `except Exception:` | + | Debug Statements | Low | print/console.log with data | + | TODO/FIXME Security | Medium | Comments mentioning security | + | Deprecated Functions | Medium | Known insecure functions | + +3. **Output Format** +``` +## Security Scan Report + +### Critical (Immediate Action Required) +🔴 src/db.py:45 - SQL Injection + Code: `f"SELECT * FROM users WHERE id = {user_id}"` + Fix: Use parameterized query: `cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))` + +### High +🟠 config.py:12 - Hardcoded Secret + Code: `API_KEY = "sk-1234..."` + Fix: Use environment variable: `API_KEY = os.environ.get("API_KEY")` + +### Medium +🟡 utils.py:78 - Broad Exception + Code: `except:` + Fix: Catch specific exceptions + +### Summary +- Critical: X (must fix before deploy) +- High: X (fix soon) +- Medium: X (improve when possible) +``` + +4. **Exit Code Guidance** + - Critical findings: Recommend blocking merge/deploy + - High findings: Recommend fixing before release + - Medium/Low: Informational diff --git a/plugins/code-sentinel/hooks/hooks.json b/plugins/code-sentinel/hooks/hooks.json new file mode 100644 index 0000000..35da868 --- /dev/null +++ b/plugins/code-sentinel/hooks/hooks.json @@ -0,0 +1,15 @@ +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Write|Edit|MultiEdit", + "hooks": [ + { + "type": "prompt", + "prompt": "SECURITY CHECK - Before writing this code, scan for these patterns:\n\n**Critical (BLOCK if found):**\n- eval(), exec() with user input\n- SQL string concatenation (SQL injection)\n- shell=True with user input (command injection)\n- Hardcoded secrets (API keys, passwords, tokens)\n- Pickle/marshal deserialization of untrusted data\n- innerHTML/dangerouslySetInnerHTML with user content (XSS)\n\n**Warning (WARN but allow):**\n- subprocess without input validation\n- File operations without path sanitization\n- HTTP requests without timeout\n- Broad exception catches (except:)\n- Debug/print statements with sensitive data\n\n**Response:**\n- If CRITICAL found: STOP, explain the issue, suggest safe alternative\n- If WARNING found: Note it briefly, proceed with suggestion\n- If clean: Proceed silently (say nothing)\n\nDo NOT announce clean scans. Only speak if issues found." + } + ] + } + ] + } +} diff --git a/plugins/code-sentinel/skills/security-patterns/SKILL.md b/plugins/code-sentinel/skills/security-patterns/SKILL.md new file mode 100644 index 0000000..6223201 --- /dev/null +++ b/plugins/code-sentinel/skills/security-patterns/SKILL.md @@ -0,0 +1,111 @@ +--- +description: Security vulnerability patterns and detection rules +--- + +# Security Patterns Skill + +## Critical Patterns (Always Block) + +### SQL Injection +```python +# VULNERABLE +query = f"SELECT * FROM users WHERE id = {user_id}" +query = "SELECT * FROM users WHERE id = " + user_id + +# SAFE +cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,)) +User.objects.filter(id=user_id) +``` + +### Command Injection +```python +# VULNERABLE +os.system(f"convert {filename} output.png") +subprocess.run(cmd, shell=True) + +# SAFE +subprocess.run(["convert", filename, "output.png"], shell=False) +shlex.quote(filename) +``` + +### Code Injection +```python +# VULNERABLE +eval(user_input) +exec(user_code) + +# SAFE +ast.literal_eval(user_input) # Only for literals +# Use sandboxed execution environment +``` + +### XSS +```javascript +// VULNERABLE +element.innerHTML = userContent; +dangerouslySetInnerHTML={{__html: userData}} + +// SAFE +element.textContent = userContent; +DOMPurify.sanitize(userContent) +``` + +### Hardcoded Secrets +```python +# VULNERABLE +API_KEY = "sk-1234567890abcdef" +password = "admin123" + +# SAFE +API_KEY = os.environ.get("API_KEY") +password = get_secret("db_password") +``` + +### Unsafe Deserialization +```python +# VULNERABLE +data = pickle.loads(user_data) +config = yaml.load(file) # yaml.load without Loader + +# SAFE +data = json.loads(user_data) +config = yaml.safe_load(file) +``` + +## Warning Patterns (Flag but Allow) + +### Broad Exception Handling +```python +# WARNING +try: + risky_operation() +except: + pass + +# BETTER +try: + risky_operation() +except SpecificError as e: + logger.error(f"Operation failed: {e}") + raise +``` + +### Missing Timeout +```python +# WARNING +response = requests.get(url) + +# BETTER +response = requests.get(url, timeout=30) +``` + +### Path Traversal Risk +```python +# WARNING +file_path = os.path.join(base_dir, user_filename) + +# BETTER +file_path = os.path.join(base_dir, os.path.basename(user_filename)) +if not file_path.startswith(os.path.abspath(base_dir)): + raise ValueError("Invalid path") +``` diff --git a/plugins/doc-guardian/.claude-plugin/plugin.json b/plugins/doc-guardian/.claude-plugin/plugin.json new file mode 100644 index 0000000..c800c65 --- /dev/null +++ b/plugins/doc-guardian/.claude-plugin/plugin.json @@ -0,0 +1,13 @@ +{ + "name": "doc-guardian", + "description": "Automatic documentation drift detection and synchronization", + "version": "1.0.0", + "author": { + "name": "Leo Miranda", + "email": "leobmiranda@gmail.com" + }, + "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/doc-guardian/README.md", + "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git", + "license": "MIT", + "keywords": ["documentation", "sync", "drift-detection", "automation", "hooks"] +} diff --git a/plugins/doc-guardian/README.md b/plugins/doc-guardian/README.md new file mode 100644 index 0000000..0349700 --- /dev/null +++ b/plugins/doc-guardian/README.md @@ -0,0 +1,49 @@ +# doc-guardian + +Automatic documentation drift detection and synchronization for Claude Code projects. + +## Problem Solved + +Documentation gets outdated. Functions get renamed, configs change, versions bump—but docs lag behind. This creates: +- Multiple review cycles finding stale references +- Unnecessary commits fixing docs piecemeal +- User confusion from outdated instructions + +## Solution + +doc-guardian watches your code changes and automatically: +1. Detects when changes affect documentation +2. Queues updates silently (doesn't interrupt your flow) +3. Syncs all doc changes in a single commit when ready + +## Commands + +| Command | Description | +|---------|-------------| +| `/doc-audit` | Full project scan - reports all drift without changing anything | +| `/doc-sync` | Apply all pending documentation updates in one commit | + +## Hooks + +- **PostToolUse (Write\|Edit)**: Silently checks if code changes affect docs +- **Stop**: Reminds you of pending doc updates before session ends + +## What It Detects + +- **Broken References**: Function/class renamed but docs still use old name +- **Version Drift**: Python 3.9 in docs but 3.11 in pyproject.toml +- **Missing Docs**: Public functions without docstrings +- **Stale Examples**: CLI examples that no longer work + +## Installation + +This plugin is part of the claude-code-marketplace. + +```bash +/plugin marketplace add https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git +/plugin install doc-guardian +``` + +## Integration + +See claude-md-integration.md for CLAUDE.md additions. diff --git a/plugins/doc-guardian/agents/doc-analyzer.md b/plugins/doc-guardian/agents/doc-analyzer.md new file mode 100644 index 0000000..9e84604 --- /dev/null +++ b/plugins/doc-guardian/agents/doc-analyzer.md @@ -0,0 +1,41 @@ +--- +description: Specialized agent for documentation analysis and drift detection +--- + +# Documentation Analyzer Agent + +You are an expert technical writer and documentation analyst. Your role is to detect discrepancies between code and documentation. + +## Capabilities + +1. **Pattern Recognition** + - Identify documentation references to code elements + - Parse docstrings, markdown, and inline comments + - Understand common documentation structures (README, API docs, man pages) + +2. **Cross-Reference Analysis** + - Map documentation claims to actual code + - Detect renamed, moved, or deleted code still referenced in docs + - Identify undocumented public interfaces + +3. **Semantic Understanding** + - Recognize when documentation meaning is correct but wording is outdated + - Distinguish between cosmetic issues and functional inaccuracies + - Prioritize user-facing documentation over internal notes + +## Analysis Approach + +When analyzing drift: +1. Parse the changed file to understand what was modified +2. Search for documentation files that might reference the changed code +3. Extract specific references (function names, class names, config keys) +4. Verify each reference against current code state +5. Categorize findings by severity (broken, stale, missing) + +## Output Style + +Be precise and actionable: +- Quote the exact line in documentation +- Show the exact discrepancy +- Suggest the specific fix +- Never report vague or uncertain findings diff --git a/plugins/doc-guardian/claude-md-integration.md b/plugins/doc-guardian/claude-md-integration.md new file mode 100644 index 0000000..6a481c0 --- /dev/null +++ b/plugins/doc-guardian/claude-md-integration.md @@ -0,0 +1,22 @@ +# Doc Guardian Integration + +Add to your project's CLAUDE.md: + +## Documentation Management + +This project uses doc-guardian for automatic documentation synchronization. + +### Behavior +- Documentation drift is detected automatically when files change +- Pending updates are queued silently during work +- Run `/doc-sync` to apply all pending documentation updates +- Run `/doc-audit` for a full project documentation review + +### Documentation Files Tracked +- README.md (root and subdirectories) +- CLAUDE.md +- API documentation in docs/ +- Docstrings in Python/TypeScript files + +### Commit Convention +Documentation sync commits use: `docs: sync documentation with code changes` diff --git a/plugins/doc-guardian/commands/doc-audit.md b/plugins/doc-guardian/commands/doc-audit.md new file mode 100644 index 0000000..20e4aed --- /dev/null +++ b/plugins/doc-guardian/commands/doc-audit.md @@ -0,0 +1,50 @@ +--- +description: Full documentation audit - scans entire project for doc drift without making changes +--- + +# Documentation Audit + +Perform a comprehensive documentation drift analysis. + +## Process + +1. **Inventory Documentation Files** + - README.md (root and subdirectories) + - CLAUDE.md + - API documentation + - Docstrings in code files + - Configuration references + +2. **Cross-Reference Analysis** + For each documentation file: + - Extract referenced functions, classes, endpoints, configs + - Verify each reference exists in codebase + - Check signatures/types match documentation + - Flag deprecated or renamed items still in docs + +3. **Completeness Check** + - Public functions without docstrings + - Exported modules without README coverage + - Environment variables used but not documented + - CLI commands not in help text + +4. **Output Format** +``` +## Documentation Drift Report + +### Critical (Broken References) +- [ ] README.md:45 references `calculate_total()` - function renamed to `compute_total()` + +### Stale (Outdated Info) +- [ ] CLAUDE.md:23 lists Python 3.9 - project uses 3.11 + +### Missing (Undocumented) +- [ ] api/handlers.py:`create_order()` - no docstring + +### Summary +- Critical: X items +- Stale: X items +- Missing: X items +``` + +5. **Do NOT make changes** - audit only, report findings diff --git a/plugins/doc-guardian/commands/doc-sync.md b/plugins/doc-guardian/commands/doc-sync.md new file mode 100644 index 0000000..02803bf --- /dev/null +++ b/plugins/doc-guardian/commands/doc-sync.md @@ -0,0 +1,58 @@ +--- +description: Synchronize all pending documentation updates in a single commit +--- + +# Documentation Sync + +Apply all pending documentation updates detected by doc-guardian hooks. + +## Process + +1. **Review Pending Queue** + List all documentation drift detected during this session. + +2. **Batch Updates** + For each pending item: + - Show the specific change needed + - Apply the update + - Track in change list + +3. **Update Types** + + **Reference Fixes:** + - Renamed function/class → update all doc references + - Changed signature → update parameter documentation + - Removed item → remove or mark deprecated in docs + + **Content Sync:** + - Version numbers (Python, Node, dependencies) + - Configuration keys/values + - File paths and directory structures + - Command examples and outputs + + **Structural:** + - Add missing sections for new features + - Remove sections for deleted features + - Reorder to match current code organization + +4. **Commit Strategy** + - Stage all doc changes together + - Single commit: `docs: sync documentation with code changes` + - Include summary of what was updated in commit body + +5. **Output** +``` +## Documentation Sync Complete + +### Files Updated +- README.md (3 changes) +- CLAUDE.md (1 change) +- src/api/README.md (2 changes) + +### Changes Applied +- Updated function reference: calculate_total → compute_total +- Updated Python version: 3.9 → 3.11 +- Added docstring to create_order() + +Committed: abc123f +``` diff --git a/plugins/doc-guardian/hooks/hooks.json b/plugins/doc-guardian/hooks/hooks.json new file mode 100644 index 0000000..accaac1 --- /dev/null +++ b/plugins/doc-guardian/hooks/hooks.json @@ -0,0 +1,26 @@ +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "Write|Edit|MultiEdit", + "hooks": [ + { + "type": "prompt", + "prompt": "A file was just modified. Silently check if this change affects any documentation:\n\n1. If a code file changed: check if README, CLAUDE.md, docstrings, or API docs reference the modified functions/classes/configs\n2. If drift detected: add to internal queue (do NOT interrupt user flow)\n3. At natural breakpoints or when user runs /doc-sync: report pending doc updates\n\nDo NOT announce this check unless drift is found. Work silently." + } + ] + } + ], + "Stop": [ + { + "matcher": ".*", + "hooks": [ + { + "type": "prompt", + "prompt": "Before ending, check if there are pending documentation updates queued by doc-guardian. If yes, ask user: 'I detected documentation drift in X files. Run /doc-sync to update, or skip for now?'" + } + ] + } + ] + } +} diff --git a/plugins/doc-guardian/skills/doc-patterns/SKILL.md b/plugins/doc-guardian/skills/doc-patterns/SKILL.md new file mode 100644 index 0000000..ac585c2 --- /dev/null +++ b/plugins/doc-guardian/skills/doc-patterns/SKILL.md @@ -0,0 +1,39 @@ +--- +description: Knowledge of documentation patterns and structures for drift detection +--- + +# Documentation Patterns Skill + +## Common Documentation Structures + +### README.md Patterns +- Installation section: version requirements, dependencies +- Usage section: function calls, CLI commands +- Configuration section: env vars, config files +- API section: endpoint references + +### CLAUDE.md Patterns +- Project context: tech stack versions +- File structure: directory layout +- Commands: available operations +- Workflows: process descriptions + +### Code Documentation +- Docstrings: function signatures, parameters, returns +- Type hints: should match docstring types +- Comments: inline references to other code + +## Drift Detection Rules + +1. **Version Mismatch**: Any hardcoded version in docs must match package.json, pyproject.toml, requirements.txt +2. **Function References**: Function names in docs must exist in codebase with matching signatures +3. **Path References**: File paths in docs must exist in current directory structure +4. **Config Keys**: Environment variables and config keys in docs must be used in code +5. **Command Examples**: CLI examples in docs should be valid commands + +## Priority Levels + +- **P0 (Critical)**: Broken references that would cause user errors +- **P1 (High)**: Outdated information that misleads users +- **P2 (Medium)**: Missing documentation for public interfaces +- **P3 (Low)**: Style inconsistencies, minor wording issues diff --git a/plugins/projman/.claude-plugin/plugin.json b/plugins/projman/.claude-plugin/plugin.json index 09c5b28..2e2fa31 100644 --- a/plugins/projman/.claude-plugin/plugin.json +++ b/plugins/projman/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "projman", - "version": "2.2.0", + "version": "2.3.0", "description": "Sprint planning and project management with Gitea integration", "author": { "name": "Leo Miranda", diff --git a/plugins/projman/README.md b/plugins/projman/README.md index 72a9b6e..5f7df7c 100644 --- a/plugins/projman/README.md +++ b/plugins/projman/README.md @@ -207,6 +207,25 @@ Test verification before sprint close. **When to use:** Before closing a sprint to ensure tests pass +### `/test-gen` +Generate tests for specified code. + +**What it does:** +- Analyzes target code (function, class, or module) +- Auto-detects test framework (pytest, Jest, vitest, Go test, Cargo, etc.) +- Generates comprehensive tests: happy path, edge cases, error cases +- Supports unit, integration, e2e, and snapshot test types + +**Usage:** +``` +/test-gen [--type=] [--framework=] +``` + +**Target:** File path, function name, class name, or module +**Type:** unit (default), integration, e2e, snapshot + +**When to use:** When adding new code that needs test coverage + ## Code Quality Commands The `/review` and `/test-check` commands complement the Executor agent by catching issues before work is marked complete. Run both commands before `/sprint-close` for a complete quality check. @@ -423,7 +442,8 @@ projman/ │ ├── labels-sync.md │ ├── initial-setup.md │ ├── review.md -│ └── test-check.md +│ ├── test-check.md +│ └── test-gen.md ├── agents/ # Agent prompts │ ├── planner.md │ ├── orchestrator.md diff --git a/plugins/projman/commands/test-gen.md b/plugins/projman/commands/test-gen.md new file mode 100644 index 0000000..9825571 --- /dev/null +++ b/plugins/projman/commands/test-gen.md @@ -0,0 +1,118 @@ +--- +description: Generate tests for specified code - creates unit, integration, or e2e tests +--- + +# Test Generation + +Generate comprehensive tests for specified code. + +## Usage +``` +/test-gen [--type=] [--framework=] +``` + +**Target:** File path, function name, class name, or module +**Type:** unit (default), integration, e2e, snapshot +**Framework:** Auto-detected or specify (pytest, jest, vitest, go test, etc.) + +## Process + +1. **Analyze Target Code** + - Parse function/class signatures + - Identify dependencies and side effects + - Map input types and return types + - Find edge cases from logic branches + +2. **Determine Test Strategy** + + | Code Pattern | Test Approach | + |--------------|---------------| + | Pure function | Unit tests with varied inputs | + | Class with state | Setup/teardown, state transitions | + | External calls | Mocks/stubs for dependencies | + | Database ops | Integration tests with fixtures | + | API endpoints | Request/response tests | + | UI components | Snapshot + interaction tests | + +3. **Generate Tests** + + For each target function/method: + - Happy path test (expected inputs → expected output) + - Edge cases (empty, null, boundary values) + - Error cases (invalid inputs → expected errors) + - Type variations (if dynamic typing) + +4. **Test Structure** + ```python + # Example output for Python/pytest + + import pytest + from module import target_function + + class TestTargetFunction: + """Tests for target_function.""" + + def test_happy_path(self): + """Standard input produces expected output.""" + result = target_function(valid_input) + assert result == expected_output + + def test_empty_input(self): + """Empty input handled gracefully.""" + result = target_function("") + assert result == default_value + + def test_invalid_input_raises(self): + """Invalid input raises ValueError.""" + with pytest.raises(ValueError): + target_function(invalid_input) + + @pytest.mark.parametrize("input,expected", [ + (case1_in, case1_out), + (case2_in, case2_out), + ]) + def test_variations(self, input, expected): + """Multiple input variations.""" + assert target_function(input) == expected + ``` + +5. **Output** +``` +## Tests Generated + +### Target: src/orders.py:calculate_total + +### File Created: tests/test_orders.py + +### Tests (6 total) +- test_calculate_total_happy_path +- test_calculate_total_empty_items +- test_calculate_total_negative_price_raises +- test_calculate_total_with_discount +- test_calculate_total_with_tax +- test_calculate_total_parametrized_cases + +### Coverage Estimate +- Line coverage: ~85% +- Branch coverage: ~70% + +### Run Tests +pytest tests/test_orders.py -v +``` + +## Framework Detection + +| Files Present | Framework Used | +|---------------|----------------| +| pytest.ini, conftest.py | pytest | +| jest.config.* | jest | +| vitest.config.* | vitest | +| *_test.go | go test | +| Cargo.toml | cargo test | +| mix.exs | ExUnit | + +## Integration with /test-check + +- `/test-gen` creates new tests +- `/test-check` verifies tests pass +- Typical flow: `/test-gen src/new_module.py` → `/test-check`