crucible-mcp 0.5.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

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/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/**"

crucible/enforcement/bundled/security.yaml

@@ -0,0 +1,123 @@
+version: "1.0"
+name: security
+description: Security assertions to catch common vulnerabilities
+linked_knowledge: SECURITY.md
+
+assertions:
+  # Critical: Code execution risks
+  - id: no-eval
+    type: pattern
+    pattern: "\\beval\\s*\\("
+    message: "eval() is dangerous - use ast.literal_eval() for data or safer alternatives"
+    severity: error
+    priority: critical
+    languages: [python, javascript, typescript]
+
+  - id: no-exec
+    type: pattern
+    pattern: "\\bexec\\s*\\("
+    message: "exec() allows arbitrary code execution - avoid or sandbox carefully"
+    severity: error
+    priority: critical
+    languages: [python]
+
+  # Critical: Shell injection
+  - id: no-shell-true
+    type: pattern
+    pattern: "shell\\s*=\\s*True"
+    message: "shell=True enables shell injection - use shell=False with argument list"
+    severity: error
+    priority: critical
+    languages: [python]
+
+  - id: no-os-system
+    type: pattern
+    pattern: "os\\.system\\s*\\("
+    message: "os.system() is vulnerable to shell injection - use subprocess with shell=False"
+    severity: error
+    priority: critical
+    languages: [python]
+
+  # Critical: Deserialization
+  - id: no-pickle-load
+    type: pattern
+    pattern: "pickle\\.load|pickle\\.loads|cPickle\\.load"
+    message: "pickle can execute arbitrary code - use json or msgpack for untrusted data"
+    severity: error
+    priority: critical
+    languages: [python]
+
+  - id: no-yaml-unsafe-load
+    type: pattern
+    pattern: "yaml\\.load\\s*\\([^)]*\\)(?!.*Loader)"
+    message: "yaml.load() without Loader is unsafe - use yaml.safe_load()"
+    severity: error
+    priority: critical
+    languages: [python]
+
+  # High: Hardcoded secrets
+  - id: no-hardcoded-password
+    type: pattern
+    pattern: "(?i)(password|passwd|pwd)\\s*=\\s*[\"'][^\"']{4,}[\"']"
+    message: "Possible hardcoded password - use environment variables or secrets manager"
+    severity: error
+    priority: high
+    applicability:
+      exclude:
+        - "**/test_*.py"
+        - "**/*_test.py"
+        - "**/tests/**"
+        - "**/*.md"
+
+  - id: no-hardcoded-api-key
+    type: pattern
+    pattern: "(?i)(api[_-]?key|apikey|secret[_-]?key)\\s*=\\s*[\"'][a-zA-Z0-9]{16,}[\"']"
+    message: "Possible hardcoded API key - use environment variables or secrets manager"
+    severity: error
+    priority: high
+    applicability:
+      exclude:
+        - "**/test_*.py"
+        - "**/*_test.py"
+        - "**/tests/**"
+        - "**/*.md"
+
+  # High: SQL injection
+  - id: no-string-sql
+    type: pattern
+    pattern: "execute\\s*\\(\\s*[\"']\\s*SELECT|execute\\s*\\(\\s*f[\"']|execute\\s*\\([^)]*%\\s*\\("
+    message: "Possible SQL injection - use parameterized queries"
+    severity: error
+    priority: high
+    languages: [python]
+
+  # Medium: Weak crypto
+  - id: no-md5-security
+    type: pattern
+    pattern: "hashlib\\.md5|MD5\\s*\\(|md5\\.new"
+    message: "MD5 is cryptographically broken - use SHA-256 or better for security"
+    severity: warning
+    priority: medium
+    languages: [python]
+
+  - id: no-sha1-security
+    type: pattern
+    pattern: "hashlib\\.sha1|SHA1\\s*\\(|sha1\\.new"
+    message: "SHA-1 is deprecated for security - use SHA-256 or better"
+    severity: warning
+    priority: medium
+    languages: [python]
+
+  # Medium: Insecure random
+  - id: no-random-for-security
+    type: pattern
+    pattern: "\\brandom\\.(choice|randint|random|uniform)\\s*\\("
+    message: "random module is not cryptographically secure - use secrets module"
+    severity: warning
+    priority: medium
+    languages: [python]
+    applicability:
+      exclude:
+        - "**/test_*.py"
+        - "**/*_test.py"
+        - "**/tests/**"

crucible/enforcement/bundled/smart-contract.yaml

@@ -0,0 +1,110 @@
+version: "1.0"
+name: smart-contract
+description: Smart contract security patterns for Solidity/Vyper
+linked_knowledge: SMART_CONTRACT.md
+
+assertions:
+  # Critical: Reentrancy
+  - id: state-after-external-call
+    type: pattern
+    pattern: "\\.call\\{[^}]*\\}\\([^)]*\\)[^;]*;[^}]*\\b(balances|_balances|userBalances|amounts)\\s*\\["
+    message: "State change after external call - potential reentrancy vulnerability (CEI violation)"
+    severity: error
+    priority: critical
+    languages: [solidity]
+
+  - id: transfer-without-reentrancy-guard
+    type: llm
+    compliance: |
+      Check for reentrancy vulnerabilities:
+      1. External calls (.call, .transfer, .send) should come AFTER state changes (CEI pattern)
+      2. Functions making external calls should have reentrancy guards (nonReentrant modifier)
+      3. State variables should be updated before external calls, not after
+      4. Check-effects-interactions pattern: checks first, then effects (state changes), then interactions (external calls)
+    message: "Potential reentrancy vulnerability - apply CEI pattern and/or nonReentrant modifier"
+    severity: error
+    priority: critical
+    model: opus
+    languages: [solidity]
+
+  # Critical: Access control
+  - id: missing-access-control
+    type: pattern
+    pattern: "function\\s+\\w+\\s*\\([^)]*\\)\\s+(external|public)(?![^{]*onlyOwner|[^{]*onlyRole|[^{]*require\\s*\\(\\s*msg\\.sender)"
+    message: "Public/external function may need access control"
+    severity: warning
+    priority: high
+    languages: [solidity]
+
+  - id: tx-origin-auth
+    type: pattern
+    pattern: "require\\s*\\(\\s*tx\\.origin\\s*==|tx\\.origin\\s*==\\s*msg\\.sender"
+    message: "tx.origin for auth is vulnerable to phishing - use msg.sender"
+    severity: error
+    priority: critical
+    languages: [solidity]
+
+  # High: Integer overflow (pre-0.8.0)
+  - id: unchecked-arithmetic
+    type: pattern
+    pattern: "unchecked\\s*\\{[^}]*[+\\-*/]"
+    message: "Unchecked arithmetic - ensure overflow/underflow is intentional and safe"
+    severity: warning
+    priority: high
+    languages: [solidity]
+
+  # High: Front-running
+  - id: block-timestamp-comparison
+    type: pattern
+    pattern: "block\\.timestamp\\s*[<>=]|[<>=]\\s*block\\.timestamp"
+    message: "block.timestamp can be manipulated by miners (~15 sec) - avoid for critical logic"
+    severity: warning
+    priority: medium
+    languages: [solidity]
+
+  # High: Denial of service
+  - id: unbounded-loop
+    type: pattern
+    pattern: "for\\s*\\([^;]*;[^;]*\\.length\\s*;"
+    message: "Loop bounded by dynamic array length - may cause out-of-gas DoS"
+    severity: warning
+    priority: high
+    languages: [solidity]
+
+  # Medium: Best practices
+  - id: missing-zero-address-check
+    type: pattern
+    pattern: "address\\s+\\w+\\s*=[^;]*;(?![^}]*require\\s*\\([^)]*!=\\s*address\\(0\\))"
+    message: "Consider checking for zero address on address parameters"
+    severity: info
+    priority: medium
+    languages: [solidity]
+
+  - id: hardcoded-gas
+    type: pattern
+    pattern: "\\.call\\{[^}]*gas:\\s*\\d+[^}]*\\}"
+    message: "Hardcoded gas values may break with EVM changes - use gasleft() or remove gas limit"
+    severity: warning
+    priority: medium
+    languages: [solidity]
+
+  # LLM: Complex security patterns
+  - id: smart-contract-security-review
+    type: llm
+    compliance: |
+      Perform a security review of this smart contract code:
+      1. Check for reentrancy vulnerabilities (external calls before state changes)
+      2. Verify access control on privileged functions
+      3. Check for integer overflow/underflow risks
+      4. Look for front-running vulnerabilities
+      5. Check for DoS vectors (unbounded loops, block gas limit issues)
+      6. Verify proper validation of external inputs
+      7. Check for unsafe delegatecall usage
+      8. Look for flash loan attack vectors
+    message: "Smart contract security issue detected"
+    severity: error
+    priority: critical
+    model: opus
+    languages: [solidity, vyper]
+    applicability:
+      glob: "**/*.sol"

crucible/enforcement/compliance.py

@@ -6,6 +6,7 @@ Supports Sonnet (default) and Opus (for high-stakes assertions).
 
 import json
 import os
+import sys
 from typing import Any
 
 from crucible.enforcement.budget import (
@@ -79,8 +80,8 @@ def _load_api_key_from_config() -> str | None:
                     key = data.get("anthropic_api_key") or data.get("ANTHROPIC_API_KEY")
                     if key:
                         return key
-            except Exception:
-                pass  # Ignore malformed config files
+            except Exception as e:
+                print(f"Warning: failed to read {config_path}: {e}", file=sys.stderr)
 
     return None
 
@@ -294,27 +295,30 @@ def run_single_assertion(
         )
 
     except ImportError as e:
+        print(f"Warning: LLM assertion '{assertion.id}' skipped: {e}", file=sys.stderr)
         return LLMAssertionResult(
             assertion_id=assertion.id,
-            passed=True,  # Don't fail on missing dependency
+            passed=True,  # Graceful degradation - don't fail on missing dependency
             findings=(),
             tokens_used=0,
             model_used=model_name,
             error=str(e),
         )
     except ValueError as e:
+        print(f"Warning: LLM assertion '{assertion.id}' skipped: {e}", file=sys.stderr)
         return LLMAssertionResult(
             assertion_id=assertion.id,
-            passed=True,  # Don't fail on missing API key
+            passed=True,  # Graceful degradation - don't fail on missing API key
             findings=(),
             tokens_used=0,
             model_used=model_name,
             error=str(e),
         )
     except Exception as e:
+        print(f"Warning: LLM assertion '{assertion.id}' failed: {e}", file=sys.stderr)
         return LLMAssertionResult(
             assertion_id=assertion.id,
-            passed=True,  # Don't fail on API errors
+            passed=True,  # Graceful degradation - don't fail on API errors
             findings=(),
             tokens_used=0,
             model_used=model_name,