crucible-mcp 0.5.0__tar.gz → 1.0.1__tar.gz

crucible_mcp-1.0.1/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: crucible-mcp
+Version: 1.0.1
+Summary: Code review MCP server for Claude. Not affiliated with Atlassian.
+Author: be.nvy
+License-Expression: MIT
+Keywords: mcp,code-review,static-analysis,claude
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: anthropic>=0.40.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: ruff>=0.3; extra == "dev"
+
+# Crucible
+
+**Your team's standards, applied by Claude, every time.**
+
+Claude without context applies generic best practices. Crucible loads *your* patterns—so Claude reviews code the way your team would, not the way the internet would.
+
+```
+├── Enforcement:   Pattern + LLM assertions that block bad code
+├── Personas:      Domain-specific thinking (how to approach problems)
+├── Knowledge:     Coding patterns and principles (what to apply)
+├── Cascade:       Project → User → Bundled (customizable at every level)
+└── Context-aware: Loads relevant skills based on what you're working on
+```
+
+**Why Crucible?**
+- **Enforcement** — Not suggestions, constraints. Assertions block code that violates your patterns
+- **Consistency** — Same checklist every time, for every engineer, every session
+- **Automation** — Runs in CI, pre-commit hooks, and Claude Code hooks
+- **Institutional knowledge** — Your senior engineer's mental checklist, in the repo
+- **Your context** — Security fundamentals plus *your* auth patterns, *your* conventions
+- **Cost efficiency** — Filter with free tools first, LLM only on what needs judgment
+
+> Not affiliated with Atlassian's Crucible.
+
+## Quick Start
+
+```bash
+pip install crucible-mcp
+
+# Initialize your project
+crucible init --with-claudemd
+
+# Install enforcement hooks
+crucible hooks install              # Git pre-commit
+crucible hooks claudecode init      # Claude Code hooks
+```
+
+That's it. Crucible will now:
+1. Run on every commit (pre-commit hook)
+2. Review files Claude edits (Claude Code hook)
+3. Block code that violates bundled assertions (security, error handling, smart contracts)
+
+## How Enforcement Works
+
+```
+Claude writes code
+    ↓
+PostToolUse hook triggers
+    ↓
+Crucible runs pattern assertions
+    ↓
+Finding detected → Exit 2 (block) + feedback to Claude
+    ↓
+Claude fixes the issue
+```
+
+**30 bundled assertions** covering:
+- Security: eval, exec, shell injection, pickle, hardcoded secrets, SQL injection
+- Error handling: bare except, silent catch, empty catch blocks
+- Smart contracts: reentrancy, CEI violations, access control, tx.origin auth
+
+**Customize with your own assertions** in `.crucible/assertions/`:
+
+```yaml
+# .crucible/assertions/my-rules.yaml
+version: "1.0"
+name: my-rules
+assertions:
+  - id: no-console-log
+    type: pattern
+    pattern: "console\\.log\\("
+    message: "Remove console.log before committing"
+    severity: warning
+    priority: medium
+    languages: [javascript, typescript]
+```
+
+## MCP Tools
+
+Add to Claude Code (`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "crucible": {
+      "command": "crucible-mcp"
+    }
+  }
+}
+```
+
+| Tool | Purpose |
+|------|---------|
+| `review(path)` | Full review: analysis + skills + knowledge + assertions |
+| `review(mode='staged')` | Review git changes with enforcement |
+| `load_knowledge(files)` | Load specific knowledge files |
+| `get_principles(topic)` | Load engineering knowledge by topic |
+| `delegate_*` | Direct tool access (semgrep, ruff, slither, bandit) |
+| `check_tools()` | Show installed analysis tools |
+
+## CLI
+
+```bash
+# Review
+crucible review                     # Review staged changes
+crucible review --mode branch       # Review current branch vs main
+crucible review src/file.py --no-git # Review without git
+
+# Assertions
+crucible assertions list            # List all assertion files
+crucible assertions test file.py    # Test assertions against a file
+
+# Hooks
+crucible hooks install              # Install pre-commit hook
+crucible hooks claudecode init      # Initialize Claude Code hooks
+
+# Customize
+crucible skills init <skill>        # Copy skill for customization
+crucible knowledge init <file>      # Copy knowledge for customization
+
+# CI
+crucible ci generate                # Generate GitHub Actions workflow
+```
+
+## Customization
+
+Everything follows cascade resolution (first found wins):
+1. `.crucible/` — Project overrides (checked into repo)
+2. `~/.claude/crucible/` — User preferences
+3. Bundled — Package defaults
+
+**Override a skill:**
+```bash
+crucible skills init security-engineer
+# Edit .crucible/skills/security-engineer/SKILL.md
+```
+
+**Add project knowledge:**
+```bash
+crucible knowledge init SECURITY
+# Edit .crucible/knowledge/SECURITY.md
+```
+
+**Add custom assertions:**
+```bash
+mkdir -p .crucible/assertions
+# Create .crucible/assertions/my-rules.yaml
+```
+
+See [CUSTOMIZATION.md](docs/CUSTOMIZATION.md) for the full guide.
+
+## What's Included
+
+**30 Bundled Assertions** — Pattern rules for security, error handling, and smart contracts.
+
+**18 Personas** — Domain-specific thinking: security, performance, accessibility, web3, backend, and more.
+
+**14 Knowledge Files** — Coding patterns and principles for security, testing, APIs, databases, smart contracts, etc.
+
+See [SKILLS.md](docs/SKILLS.md) and [KNOWLEDGE.md](docs/KNOWLEDGE.md) for details.
+
+## Documentation
+
+| Doc | What's In It |
+|-----|--------------|
+| [QUICKSTART.md](docs/QUICKSTART.md) | 5-minute setup guide |
+| [FEATURES.md](docs/FEATURES.md) | Complete feature reference |
+| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | How MCP, tools, skills, and knowledge fit together |
+| [CUSTOMIZATION.md](docs/CUSTOMIZATION.md) | Override skills and knowledge for your project |
+| [SKILLS.md](docs/SKILLS.md) | All 18 personas with triggers and focus areas |
+| [KNOWLEDGE.md](docs/KNOWLEDGE.md) | All 14 knowledge files with topics covered |
+| [CONTRIBUTING.md](docs/CONTRIBUTING.md) | Adding tools, skills, and knowledge |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                    # Run tests (580+ tests)
+ruff check src/ --fix     # Lint
+```

crucible_mcp-1.0.1/README.md

@@ -0,0 +1,180 @@
+# Crucible
+
+**Your team's standards, applied by Claude, every time.**
+
+Claude without context applies generic best practices. Crucible loads *your* patterns—so Claude reviews code the way your team would, not the way the internet would.
+
+```
+├── Enforcement:   Pattern + LLM assertions that block bad code
+├── Personas:      Domain-specific thinking (how to approach problems)
+├── Knowledge:     Coding patterns and principles (what to apply)
+├── Cascade:       Project → User → Bundled (customizable at every level)
+└── Context-aware: Loads relevant skills based on what you're working on
+```
+
+**Why Crucible?**
+- **Enforcement** — Not suggestions, constraints. Assertions block code that violates your patterns
+- **Consistency** — Same checklist every time, for every engineer, every session
+- **Automation** — Runs in CI, pre-commit hooks, and Claude Code hooks
+- **Institutional knowledge** — Your senior engineer's mental checklist, in the repo
+- **Your context** — Security fundamentals plus *your* auth patterns, *your* conventions
+- **Cost efficiency** — Filter with free tools first, LLM only on what needs judgment
+
+> Not affiliated with Atlassian's Crucible.
+
+## Quick Start
+
+```bash
+pip install crucible-mcp
+
+# Initialize your project
+crucible init --with-claudemd
+
+# Install enforcement hooks
+crucible hooks install              # Git pre-commit
+crucible hooks claudecode init      # Claude Code hooks
+```
+
+That's it. Crucible will now:
+1. Run on every commit (pre-commit hook)
+2. Review files Claude edits (Claude Code hook)
+3. Block code that violates bundled assertions (security, error handling, smart contracts)
+
+## How Enforcement Works
+
+```
+Claude writes code
+    ↓
+PostToolUse hook triggers
+    ↓
+Crucible runs pattern assertions
+    ↓
+Finding detected → Exit 2 (block) + feedback to Claude
+    ↓
+Claude fixes the issue
+```
+
+**30 bundled assertions** covering:
+- Security: eval, exec, shell injection, pickle, hardcoded secrets, SQL injection
+- Error handling: bare except, silent catch, empty catch blocks
+- Smart contracts: reentrancy, CEI violations, access control, tx.origin auth
+
+**Customize with your own assertions** in `.crucible/assertions/`:
+
+```yaml
+# .crucible/assertions/my-rules.yaml
+version: "1.0"
+name: my-rules
+assertions:
+  - id: no-console-log
+    type: pattern
+    pattern: "console\\.log\\("
+    message: "Remove console.log before committing"
+    severity: warning
+    priority: medium
+    languages: [javascript, typescript]
+```
+
+## MCP Tools
+
+Add to Claude Code (`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "crucible": {
+      "command": "crucible-mcp"
+    }
+  }
+}
+```
+
+| Tool | Purpose |
+|------|---------|
+| `review(path)` | Full review: analysis + skills + knowledge + assertions |
+| `review(mode='staged')` | Review git changes with enforcement |
+| `load_knowledge(files)` | Load specific knowledge files |
+| `get_principles(topic)` | Load engineering knowledge by topic |
+| `delegate_*` | Direct tool access (semgrep, ruff, slither, bandit) |
+| `check_tools()` | Show installed analysis tools |
+
+## CLI
+
+```bash
+# Review
+crucible review                     # Review staged changes
+crucible review --mode branch       # Review current branch vs main
+crucible review src/file.py --no-git # Review without git
+
+# Assertions
+crucible assertions list            # List all assertion files
+crucible assertions test file.py    # Test assertions against a file
+
+# Hooks
+crucible hooks install              # Install pre-commit hook
+crucible hooks claudecode init      # Initialize Claude Code hooks
+
+# Customize
+crucible skills init <skill>        # Copy skill for customization
+crucible knowledge init <file>      # Copy knowledge for customization
+
+# CI
+crucible ci generate                # Generate GitHub Actions workflow
+```
+
+## Customization
+
+Everything follows cascade resolution (first found wins):
+1. `.crucible/` — Project overrides (checked into repo)
+2. `~/.claude/crucible/` — User preferences
+3. Bundled — Package defaults
+
+**Override a skill:**
+```bash
+crucible skills init security-engineer
+# Edit .crucible/skills/security-engineer/SKILL.md
+```
+
+**Add project knowledge:**
+```bash
+crucible knowledge init SECURITY
+# Edit .crucible/knowledge/SECURITY.md
+```
+
+**Add custom assertions:**
+```bash
+mkdir -p .crucible/assertions
+# Create .crucible/assertions/my-rules.yaml
+```
+
+See [CUSTOMIZATION.md](docs/CUSTOMIZATION.md) for the full guide.
+
+## What's Included
+
+**30 Bundled Assertions** — Pattern rules for security, error handling, and smart contracts.
+
+**18 Personas** — Domain-specific thinking: security, performance, accessibility, web3, backend, and more.
+
+**14 Knowledge Files** — Coding patterns and principles for security, testing, APIs, databases, smart contracts, etc.
+
+See [SKILLS.md](docs/SKILLS.md) and [KNOWLEDGE.md](docs/KNOWLEDGE.md) for details.
+
+## Documentation
+
+| Doc | What's In It |
+|-----|--------------|
+| [QUICKSTART.md](docs/QUICKSTART.md) | 5-minute setup guide |
+| [FEATURES.md](docs/FEATURES.md) | Complete feature reference |
+| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | How MCP, tools, skills, and knowledge fit together |
+| [CUSTOMIZATION.md](docs/CUSTOMIZATION.md) | Override skills and knowledge for your project |
+| [SKILLS.md](docs/SKILLS.md) | All 18 personas with triggers and focus areas |
+| [KNOWLEDGE.md](docs/KNOWLEDGE.md) | All 14 knowledge files with topics covered |
+| [CONTRIBUTING.md](docs/CONTRIBUTING.md) | Adding tools, skills, and knowledge |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                    # Run tests (580+ tests)
+ruff check src/ --fix     # Lint
+```

{crucible_mcp-0.5.0 → crucible_mcp-1.0.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "crucible-mcp"
-version = "0.5.0"
+version = "1.0.1"
 description = "Code review MCP server for Claude. Not affiliated with Atlassian."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -33,6 +33,13 @@ build-backend = "setuptools.build_meta"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+crucible = [
+    "skills/**/*.md",
+    "knowledge/principles/*.md",
+    "enforcement/bundled/*.yaml",
+]
+
 [tool.ruff]
 line-length = 100
 target-version = "py311"

{crucible_mcp-0.5.0 → crucible_mcp-1.0.1}/src/crucible/cli.py

@@ -578,6 +578,27 @@ def _cmd_review_no_git(args: argparse.Namespace, path: str) -> int:
     # Deduplicate
     all_findings = deduplicate_findings(all_findings)
 
+    # Run enforcement assertions
+    from crucible.review.core import run_enforcement
+
+    compliance_config = _build_compliance_config(
+        config,
+        cli_token_budget=getattr(args, "token_budget", None),
+        cli_model=getattr(args, "compliance_model", None),
+        cli_no_compliance=getattr(args, "no_compliance", False),
+    )
+
+    # Use current directory as repo root for enforcement
+    enforcement_findings, enforcement_errors, assertions_checked, assertions_skipped, budget_state = (
+        run_enforcement(
+            ".",
+            changed_files=files_to_analyze,
+            repo_root=".",
+            compliance_config=compliance_config,
+        )
+    )
+    tool_errors.extend(enforcement_errors)
+
     # Compute severity summary
     severity_counts = compute_severity_counts(all_findings)
 
@@ -607,6 +628,21 @@ def _cmd_review_no_git(args: argparse.Namespace, path: str) -> int:
                 }
                 for f in all_findings
             ],
+            "enforcement": {
+                "findings": [
+                    {
+                        "assertion_id": f.assertion_id,
+                        "severity": f.severity,
+                        "message": f.message,
+                        "location": f.location,
+                        "source": f.source,
+                    }
+                    for f in enforcement_findings
+                ],
+                "assertions_checked": assertions_checked,
+                "assertions_skipped": assertions_skipped,
+                "tokens_used": budget_state.tokens_used if budget_state else 0,
+            },
             "severity_counts": severity_counts,
             "passed": passed,
             "threshold": default_threshold.value if default_threshold else None,
@@ -616,7 +652,7 @@ def _cmd_review_no_git(args: argparse.Namespace, path: str) -> int:
     else:
         # Text output
         if all_findings:
-            print(f"\nFound {len(all_findings)} issue(s):\n")
+            print(f"\nFound {len(all_findings)} static analysis issue(s):\n")
             for f in all_findings:
                 sev_icon = {"critical": "🔴", "high": "🟠", "medium": "🟡", "low": "🔵", "info": "⚪"}.get(
                     f.severity.value, "⚪"
@@ -626,7 +662,18 @@ def _cmd_review_no_git(args: argparse.Namespace, path: str) -> int:
                 if f.suggestion:
                     print(f"   💡 {f.suggestion}")
                 print()
-        else:
+
+        # Enforcement findings
+        if enforcement_findings:
+            print(f"\nEnforcement Assertions ({len(enforcement_findings)}):")
+            for f in enforcement_findings:
+                sev_icon = {"error": "🔴", "warning": "🟠", "info": "⚪"}.get(f.severity, "⚪")
+                source_tag = "[LLM]" if f.source == "llm" else "[Pattern]"
+                print(f"  {sev_icon} [{f.severity.upper()}] {source_tag} {f.assertion_id}: {f.location}")
+                print(f"    {f.message}")
+                print()
+
+        if not all_findings and not enforcement_findings:
             print("\n✅ No issues found.")
 
         # Summary
@@ -634,6 +681,11 @@ def _cmd_review_no_git(args: argparse.Namespace, path: str) -> int:
             counts_str = ", ".join(f"{k}: {v}" for k, v in severity_counts.items() if v > 0)
             print(f"Summary: {counts_str}")
 
+        if assertions_checked or assertions_skipped:
+            print(f"Assertions: {assertions_checked} checked, {assertions_skipped} skipped")
+            if budget_state and budget_state.tokens_used > 0:
+                print(f"  LLM tokens used: {budget_state.tokens_used}")
+
         if tool_errors and not args.quiet:
             print(f"\n⚠️  {len(tool_errors)} tool error(s)")
             for err in tool_errors[:5]:
@@ -1682,11 +1734,30 @@ include_context: false
     if not gitignore_path.exists():
         gitignore_path.write_text("# Local overrides (optional)\n*.local.md\n")
 
+    # Create minimal CLAUDE.md if requested
+    if args.with_claudemd:
+        claudemd_path = project_path / "CLAUDE.md"
+        if claudemd_path.exists() and not args.force:
+            print(f"Warning: {claudemd_path} exists, skipping (use --force to overwrite)")
+        else:
+            project_name = project_path.name
+            claudemd_content = f"""# {project_name}
+
+Use Crucible for code review: `crucible review`
+
+For full engineering principles and patterns, run:
+- `crucible knowledge list` - see available knowledge
+- `crucible skills list` - see available review personas
+"""
+            claudemd_path.write_text(claudemd_content)
+            print(f"Created {claudemd_path}")
+
     print(f"\nInitialized {crucible_dir}")
     print("\nNext steps:")
     print("  1. Customize skills:     crucible skills init <skill>")
     print("  2. Customize knowledge:  crucible knowledge init <file>")
     print("  3. Install git hooks:    crucible hooks install")
+    print("  4. Claude Code hooks:    crucible hooks claudecode init")
     return 0
 
 
@@ -1950,6 +2021,28 @@ def main() -> int:
         "path", nargs="?", default=".", help="Repository path"
     )
 
+    # hooks claudecode
+    hooks_claudecode_parser = hooks_sub.add_parser(
+        "claudecode",
+        help="Claude Code hooks integration"
+    )
+    hooks_claudecode_sub = hooks_claudecode_parser.add_subparsers(dest="claudecode_command")
+
+    # hooks claudecode init
+    hooks_cc_init_parser = hooks_claudecode_sub.add_parser(
+        "init",
+        help="Initialize Claude Code hooks for project"
+    )
+    hooks_cc_init_parser.add_argument(
+        "path", nargs="?", default=".", help="Project path"
+    )
+
+    # hooks claudecode hook (called by Claude Code)
+    hooks_claudecode_sub.add_parser(
+        "hook",
+        help="Run hook (reads JSON from stdin)"
+    )
+
     # === review command ===
     review_parser = subparsers.add_parser(
         "review",
@@ -2044,6 +2137,10 @@ def main() -> int:
         "--minimal", action="store_true",
         help="Create minimal config without copying skills"
     )
+    init_proj_parser.add_argument(
+        "--with-claudemd", action="store_true",
+        help="Generate minimal CLAUDE.md that points to Crucible"
+    )
     init_proj_parser.add_argument(
         "path", nargs="?", default=".",
         help="Project path (default: current directory)"
@@ -2161,6 +2258,15 @@ def main() -> int:
             return cmd_hooks_uninstall(args)
         elif args.hooks_command == "status":
             return cmd_hooks_status(args)
+        elif args.hooks_command == "claudecode":
+            from crucible.hooks.claudecode import main_init, run_hook
+            if args.claudecode_command == "init":
+                return main_init(args.path)
+            elif args.claudecode_command == "hook":
+                return run_hook()
+            else:
+                hooks_claudecode_parser.print_help()
+                return 0
         else:
             hooks_parser.print_help()
             return 0
@@ -2211,6 +2317,7 @@ def main() -> int:
         print("  crucible hooks install          Install pre-commit hook to .git/hooks/")
         print("  crucible hooks uninstall        Remove pre-commit hook")
         print("  crucible hooks status           Show hook installation status")
+        print("  crucible hooks claudecode init  Initialize Claude Code hooks")
         print()
         print("  crucible assertions list        List assertion files from all sources")
         print("  crucible assertions validate    Validate assertion files")

crucible_mcp-1.0.1/src/crucible/enforcement/bundled/error-handling.yaml

@@ -0,0 +1,84 @@
+version: "1.0"
+name: error-handling
+description: Error handling best practices to prevent silent failures
+linked_knowledge: ERROR_HANDLING.md
+
+assertions:
+  # High: Silent failures
+  - id: no-bare-except
+    type: pattern
+    pattern: "except\\s*:"
+    message: "Bare except catches everything including SystemExit/KeyboardInterrupt - catch specific exceptions"
+    severity: warning
+    priority: high
+    languages: [python]
+
+  - id: no-pass-in-except
+    type: pattern
+    pattern: "except[^:]*:\\s*\\n\\s*pass\\s*$"
+    message: "Empty except block silently swallows errors - log or re-raise"
+    severity: warning
+    priority: high
+    languages: [python]
+
+  - id: no-empty-catch
+    type: pattern
+    pattern: "catch\\s*\\([^)]*\\)\\s*\\{\\s*\\}"
+    message: "Empty catch block silently swallows errors - log or re-throw"
+    severity: warning
+    priority: high
+    languages: [javascript, typescript]
+
+  # Medium: Pokemon exception handling
+  - id: no-catch-exception
+    type: pattern
+    pattern: "except\\s+Exception\\s*:"
+    message: "Catching Exception is too broad - catch specific exception types"
+    severity: info
+    priority: medium
+    languages: [python]
+
+  - id: no-catch-base-exception
+    type: pattern
+    pattern: "except\\s+BaseException\\s*:"
+    message: "Catching BaseException includes SystemExit/KeyboardInterrupt - use Exception or specific types"
+    severity: warning
+    priority: medium
+    languages: [python]
+
+  # Medium: Error suppression
+  - id: no-ignore-errors-flag
+    type: pattern
+    pattern: "errors\\s*=\\s*[\"']ignore[\"']"
+    message: "errors='ignore' silently drops data - use 'replace' or handle explicitly"
+    severity: warning
+    priority: medium
+    languages: [python]
+
+  # Info: Best practices
+  - id: prefer-contextlib-suppress
+    type: pattern
+    pattern: "except\\s+\\w+\\s*:\\s*\\n\\s*pass\\s*$"
+    message: "Consider contextlib.suppress() for intentionally ignoring specific exceptions"
+    severity: info
+    priority: low
+    languages: [python]
+
+  # LLM assertion for complex error handling patterns
+  - id: error-handling-semantic
+    type: llm
+    compliance: |
+      Check that error handling follows best practices:
+      1. Errors are not silently swallowed (no empty except/catch blocks that do nothing)
+      2. Exceptions are logged or reported before being suppressed
+      3. Error messages provide enough context to debug issues
+      4. Errors at API/system boundaries are handled (not just propagated)
+    message: "Error handling may need improvement"
+    severity: warning
+    priority: medium
+    languages: [python, javascript, typescript]
+    applicability:
+      exclude:
+        - "**/test_*.py"
+        - "**/*_test.py"
+        - "**/tests/**"