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

crucible/knowledge/principles/OBSERVABILITY.md

@@ -0,0 +1,147 @@
+---
+name: Observability
+description: Logging, metrics, tracing, alerting patterns
+triggers: [logging, monitoring, metrics, tracing, observability]
+type: pattern
+---
+
+# Observability Principles
+
+Logs, metrics, traces, and alerting patterns.
+
+---
+
+## The Triad
+
+```
+Logs:    What happened (events, errors)
+Metrics: How much (counters, gauges, histograms)
+Traces:  Where (request flow across services)
+```
+
+---
+
+## Minimum Viable Observability
+
+```
+├── Structured logs (JSON, not strings)
+├── Error tracking (Sentry)
+├── Basic metrics (response times, error rates)
+├── Health check endpoint
+└── Alerts on SLOs
+```
+
+---
+
+## Structured Logging
+
+```typescript
+// String concatenation (hard to parse)
+console.log(`Created tip ${tipId} for page ${pageId}`);
+
+// Structured (queryable, machine-readable)
+log.info("Tip created", {
+  tipId,
+  pageId,
+  amountCents,
+  timestamp: new Date().toISOString(),
+});
+```
+
+---
+
+## Log Levels
+
+```
+ERROR   → Something broke, needs attention
+WARN    → Something unexpected, may need attention
+INFO    → Normal operation, useful for debugging
+DEBUG   → Detailed info, usually disabled in prod
+```
+
+---
+
+## Health Checks
+
+Every service needs health endpoints:
+
+```typescript
+// Simple health check
+GET /health
+{ status: "ok" }
+
+// Detailed health check
+GET /health/ready
+{
+  status: "ok",
+  checks: {
+    database: "ok",
+    redis: "ok",
+    externalApi: "degraded"
+  }
+}
+```
+
+---
+
+## Metrics to Track
+
+```
+├── Request rate (requests/second)
+├── Error rate (errors/requests)
+├── Latency (p50, p95, p99)
+├── Saturation (CPU, memory, connections)
+└── Business metrics (signups, purchases)
+```
+
+---
+
+## Alerting
+
+```
+Alert on SLOs, not symptoms:
+├── CPU > 80% (less useful)
+├── Error rate > 1% for 5 minutes (actionable)
+├── p99 latency > 500ms for 10 minutes (actionable)
+
+Runnable alerts include:
+├── What's broken?
+├── How to verify?
+├── How to fix?
+├── Who to escalate to?
+```
+
+---
+
+## Correlation IDs
+
+Trace requests across services:
+
+```typescript
+// Generate at edge
+const correlationId = req.headers['x-correlation-id'] || uuid();
+
+// Pass to all downstream calls
+await fetch(url, {
+  headers: { 'x-correlation-id': correlationId }
+});
+
+// Include in all logs
+log.info("Processing request", { correlationId, ... });
+```
+
+---
+
+## Observability Budget
+
+Plan observability for each feature:
+
+```
+├── What metrics will you track?
+├── What alerts will fire?
+├── How will you debug in production?
+```
+
+---
+
+*Template. Adapt to your needs.*

crucible/knowledge/principles/PRECOMMIT.md

@@ -0,0 +1,201 @@
+---
+name: Pre-commit Hooks
+description: Automated checks before commits - linting, formatting, secrets
+triggers: [precommit, hooks, linting, formatting]
+type: pattern
+---
+
+# Pre-commit Hook Principles
+
+Automated guardrails before code enters the repo.
+
+---
+
+## Setup
+
+```bash
+pip install pre-commit
+pre-commit install
+pre-commit run --all-files  # Initial scan
+```
+
+Config: `.pre-commit-config.yaml`
+
+---
+
+## Secret Detection (Critical)
+
+Layer multiple scanners for defense-in-depth:
+
+```yaml
+repos:
+  # Gitleaks - comprehensive secret scanner
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.18.1
+    hooks:
+      - id: gitleaks
+
+  # Detect-secrets by Yelp - another layer
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.4.0
+    hooks:
+      - id: detect-secrets
+        args: ['--baseline', '.secrets.baseline']
+
+  # Built-in checks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: detect-private-key
+      - id: detect-aws-credentials
+```
+
+---
+
+## Custom Secret Scanner
+
+For high-confidence patterns:
+
+```bash
+HIGH_CONFIDENCE_PATTERNS=(
+    # AWS
+    'AKIA[0-9A-Z]{16}'
+
+    # GitHub tokens
+    'ghp_[A-Za-z0-9]{36}'
+    'gho_[A-Za-z0-9]{36}'
+
+    # API keys
+    'sk-[A-Za-z0-9]{48}'           # OpenAI
+    'sk-ant-[A-Za-z0-9\-]{80,}'    # Anthropic
+
+    # Private keys
+    '-----BEGIN (RSA |EC )?PRIVATE KEY-----'
+
+    # Database URLs with passwords
+    'postgres://[^:]+:[^@]+@'
+    'mongodb://[^:]+:[^@]+@'
+)
+```
+
+---
+
+## Python Hooks
+
+```yaml
+# Ruff - fast linter
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.3.0
+  hooks:
+    - id: ruff
+      args: [--fix]
+    - id: ruff-format
+
+# MyPy - type checking
+- repo: https://github.com/pre-commit/mirrors-mypy
+  rev: v1.8.0
+  hooks:
+    - id: mypy
+      additional_dependencies: [types-all]
+      args: [--strict]
+```
+
+---
+
+## File Hygiene
+
+```yaml
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.5.0
+  hooks:
+    - id: trailing-whitespace
+    - id: end-of-file-fixer
+    - id: check-yaml
+    - id: check-json
+    - id: check-toml
+    - id: check-added-large-files
+      args: ['--maxkb=500']
+    - id: check-merge-conflict
+```
+
+---
+
+## Commit Message Validation
+
+```yaml
+- repo: https://github.com/commitizen-tools/commitizen
+  rev: v3.13.0
+  hooks:
+    - id: commitizen
+      stages: [commit-msg]
+```
+
+Enforces semantic commit format: `(type): description`
+
+---
+
+## CI Integration
+
+```yaml
+ci:
+  autofix_commit_msg: |
+    [pre-commit.ci] auto fixes from hooks
+  autofix_prs: true
+  autoupdate_schedule: weekly
+```
+
+---
+
+## Skip Patterns
+
+Files to exclude from scanning:
+
+```bash
+SKIP_PATTERNS=(
+    '\.lock$'
+    'package-lock\.json$'
+    '\.min\.js$'
+    'vendor/'
+    'node_modules/'
+)
+```
+
+---
+
+## Blocked Commit Response
+
+```
+============================================================
+COMMIT BLOCKED: Potential secrets detected!
+============================================================
+
+If these are false positives, you can:
+  1. Add patterns to .gitignore
+  2. Use 'git commit --no-verify' (NOT RECOMMENDED)
+  3. Add file to hooks/secrets-allowlist.txt
+```
+
+---
+
+## Anti-patterns
+
+```yaml
+# Bad: no secret detection
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    hooks:
+      - id: trailing-whitespace
+
+# Bad: single layer of detection
+# (one tool might miss what another catches)
+
+# Bad: skipping hooks in CI
+skip: [gitleaks, detect-secrets]
+
+# Bad: loose file size limits
+args: ['--maxkb=10000']
+```
+
+---
+
+*Pair with comprehensive .gitignore for defense-in-depth.*

crucible/knowledge/principles/SECURITY.md

@@ -0,0 +1,136 @@
+---
+name: Security Principles
+description: Core security principles - input validation, secrets, injection prevention
+triggers: [security, auth, crypto, api, secrets, injection]
+type: principle
+assertions: security.yaml
+---
+
+# Security Principles
+
+Quick reference for secure code patterns.
+
+---
+
+## Review Checklist
+
+```
+[ ] Dependencies updated (npm audit, pip audit)
+[ ] No secrets in code or logs
+[ ] Input validation on all endpoints
+[ ] Rate limiting on sensitive routes
+[ ] HTTPS everywhere
+[ ] Auth on protected routes
+[ ] CORS configured correctly
+[ ] CSP headers set
+[ ] SQL injection impossible (ORM/parameterized)
+[ ] XSS prevented (escaped output)
+[ ] CSRF tokens on forms
+[ ] Audit logging for sensitive operations
+```
+
+---
+
+## Input Validation
+
+Validate at every trust boundary.
+
+```typescript
+const handler = (req: Request) => {
+  const result = InputSchema.safeParse(req.body);
+  if (!result.success) {
+    return Response.json({ error: 'Invalid input' }, { status: 400 });
+  }
+  // Proceed with validated data
+};
+```
+
+---
+
+## Query Safety
+
+```typescript
+// SQL injection risk
+const query = `SELECT * FROM users WHERE id = '${userId}'`;
+
+// Parameterized (ORMs do this automatically)
+const user = await prisma.user.findUnique({ where: { id: userId } });
+```
+
+---
+
+## Secrets Management
+
+```
+├── Env vars, not in code
+├── Rotate on any suspected leak
+├── Mask secrets in logs
+├── Different secrets per environment
+└── Use secret managers in production
+```
+
+---
+
+## Defense in Depth
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  PREVENTION                                              │
+│  Input validation, auth checks, rate limiting           │
+└───────────────────────────┬─────────────────────────────┘
+                            │ if prevention fails
+                            ▼
+┌─────────────────────────────────────────────────────────┐
+│  DETECTION                                               │
+│  Logging, monitoring, alerts, anomaly detection         │
+└───────────────────────────┬─────────────────────────────┘
+                            │ when detected
+                            ▼
+┌─────────────────────────────────────────────────────────┐
+│  RESPONSE                                                │
+│  Incident runbook, secret rotation, access revocation   │
+└───────────────────────────┬─────────────────────────────┘
+                            │ after response
+                            ▼
+┌─────────────────────────────────────────────────────────┐
+│  RECOVERY                                                │
+│  Backups, audit trail, rollback, post-mortem            │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Deserialization Safety
+
+Do not deserialize untrusted data into objects that can execute code.
+
+| Library | Dangerous | Safe Alternative |
+|---------|-----------|------------------|
+| Python | `pickle.load()`, `eval()` | `json.load()` |
+| PyYAML | `yaml.load()` | `yaml.safe_load()` |
+| subprocess | `shell=True` + user input | `shell=False`, explicit args |
+
+**Principle:** If it can reconstruct arbitrary objects, it can execute arbitrary code.
+
+---
+
+## Risk Surface Mapping
+
+```
+Step 1: Map Data Flows
+├── Where does data come from?
+├── Where does it go?
+├── Who can access it?
+└── What's the impact if wrong/leaked/lost?
+
+Step 2: Categorize Risks
+├── Data Integrity     → Wrong data stored
+├── Confidentiality    → Sensitive data exposed
+├── Auth Bypass        → Unauthorized access
+├── Injection          → SQL, XSS, command injection
+└── Denial of Service  → Resource exhaustion
+```
+
+---
+
+*Template. Adapt to your needs.*

crucible/knowledge/principles/SMART_CONTRACT.md

@@ -0,0 +1,153 @@
+---
+name: Smart Contract Principles
+description: EVM patterns - reentrancy, CEI, gas optimization, upgrade safety
+triggers: [solidity, smart-contract, web3, evm, ethereum, blockchain]
+type: principle
+assertions: smart-contract.yaml
+---
+
+# Smart Contract Principles
+
+---
+
+## The EVM Cost Model
+
+```
+TRADITIONAL BACKEND:         SMART CONTRACTS:
+├── State is cheap            State costs ~20k gas/32 bytes
+├── Computation is cheap      Computation costs gas
+├── Side effects are "free"   Side effects cost gas + risk
+├── Bugs are fixable          Deployed code is immutable
+└── Complexity is manageable  Complexity increases attack surface
+```
+
+---
+
+## Review Checklist
+
+```
+[ ] CEI pattern followed (Checks-Effects-Interactions)
+[ ] Reentrancy guards on external call + value functions
+[ ] No tx.origin for authentication
+[ ] Address zero checks on critical params
+[ ] Slither clean (or findings documented)
+[ ] Access control on privileged functions
+[ ] Events emitted for state changes
+[ ] No hardcoded addresses (use immutable/constructor)
+```
+
+---
+
+## CEI Pattern
+
+Checks-Effects-Interactions:
+
+```solidity
+// Safe: CEI pattern
+function withdraw() external {
+    uint256 amount = balances[msg.sender];  // CHECK
+    balances[msg.sender] = 0;               // EFFECT (state first)
+    (bool success, ) = msg.sender.call{value: amount}("");  // INTERACTION
+    require(success, "Transfer failed");
+}
+
+// Unsafe: Interaction before effect = reentrancy
+function withdraw() external {
+    uint256 amount = balances[msg.sender];
+    (bool success, ) = msg.sender.call{value: amount}("");  // INTERACTION
+    balances[msg.sender] = 0;  // EFFECT after = vulnerable
+}
+```
+
+---
+
+## State Optimization
+
+```solidity
+// Constant: Compile-time, zero gas to read
+uint256 public constant MAX_FEE = 1000;
+
+// Immutable: Set once in constructor, cheaper reads
+address public immutable owner;
+
+// Storage: 20,000 gas to set, 2,100 gas to read
+uint256 public mutableValue;
+```
+
+---
+
+## Common Vulnerabilities
+
+### Reentrancy
+```solidity
+// Use ReentrancyGuard
+import "@openzeppelin/contracts/security/ReentrancyGuard.sol";
+
+function withdraw() external nonReentrant { ... }
+```
+
+### tx.origin
+```solidity
+// Vulnerable to phishing
+require(tx.origin == owner);
+
+// Use msg.sender
+require(msg.sender == owner);
+```
+
+### Unchecked Returns
+```solidity
+// Ignoring return value
+token.transfer(to, amount);
+
+// Using SafeERC20
+using SafeERC20 for IERC20;
+token.safeTransfer(to, amount);
+```
+
+---
+
+## Security Invariants
+
+Properties that must hold:
+
+```
+1. Conservation: sum(balances) == totalSupply
+2. No over-withdrawal: user.withdrawn <= user.entitled
+3. Monotonicity: Open → Settling → Closed (state transitions)
+4. Access: only owner can call admin functions
+```
+
+Test invariants with fuzzing (Foundry, Echidna).
+
+---
+
+## Gas Optimization
+
+Cache values in hot paths:
+
+```solidity
+// Cache array length
+uint256 len = values.length;
+for (uint256 i; i < len; ) {
+    total += values[i];
+    unchecked { ++i; }  // Safe when i < len
+}
+```
+
+Prioritize clarity for infrequent operations.
+
+---
+
+## Anti-Patterns
+
+```
+- Premature upgradeability (adds complexity, admin risk)
+- Deep inheritance (hard to audit)
+- God contracts (too much in one place)
+- Magic numbers (use constants)
+```
+
+---
+
+*Template. Adapt to your needs.*