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

crucible/knowledge/principles/DOCUMENTATION.md

@@ -0,0 +1,201 @@
+---
+name: Documentation
+description: Code comments, READMEs, API docs, architecture docs
+triggers: [docs, documentation, readme, comments]
+type: preference
+---
+
+# Documentation Principles
+
+What to document, where to put it, and how to keep it useful.
+
+---
+
+## The Docs Folder
+
+```
+docs/
+├── FEATURES.md      # What the project does (capabilities)
+├── ROADMAP.md       # What's planned (timeline + status)
+├── ARCHITECTURE.md  # How it works (diagrams + data flow)
+└── design-*.md      # Decision docs for specific features
+```
+
+---
+
+## FEATURES.md
+
+Complete reference for all capabilities.
+
+```markdown
+# Project Features
+
+## Overview
+[ASCII diagram showing the system]
+
+## Feature Category 1
+
+### Feature A
+- What it does
+- How to use it
+- Configuration options
+
+### Feature B
+...
+
+## CLI Commands
+| Command | Purpose |
+|---------|---------|
+| `cmd list` | List items |
+| `cmd add` | Add item |
+```
+
+---
+
+## ROADMAP.md
+
+Version timeline and planned features.
+
+```markdown
+# Roadmap
+
+## Current: vX.Y (Month Year)
+
+### What's Shipped
+| Feature | Status | Notes |
+|---------|--------|-------|
+| Feature A | Done | Details |
+| Feature B | Done | Details |
+
+## vX.Z (Planned)
+
+### Focus: Theme
+| Feature | Description |
+|---------|-------------|
+| Feature C | What it will do |
+
+## Version History
+| Version | Date | Highlights |
+|---------|------|------------|
+| v1.0 | Jan 2026 | Initial release |
+```
+
+---
+
+## ARCHITECTURE.md
+
+System design and data flow.
+
+```markdown
+# Architecture
+
+## Overview
+[ASCII or Mermaid diagram]
+
+## Components
+| Component | Purpose |
+|-----------|---------|
+| api/ | HTTP handlers |
+| core/ | Business logic |
+
+## Data Flow
+[Sequence diagram]
+
+## File Structure
+```
+src/
+├── api/      # HTTP layer
+├── core/     # Business logic
+└── db/       # Database access
+```
+```
+
+---
+
+## Design Docs
+
+For significant decisions:
+
+```markdown
+# Design: Feature Name
+
+## Context
+What problem are we solving?
+
+## Options Considered
+1. **Option A**: Pros/cons
+2. **Option B**: Pros/cons
+
+## Decision
+We chose Option A because...
+
+## Consequences
+- Positive: X
+- Negative: Y
+- Neutral: Z
+```
+
+---
+
+## README.md
+
+Quick start only:
+
+```markdown
+# Project Name
+
+One-line description.
+
+## Quick Start
+\`\`\`bash
+pip install project
+project init
+\`\`\`
+
+## Documentation
+- [Features](docs/FEATURES.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Roadmap](docs/ROADMAP.md)
+```
+
+---
+
+## CLAUDE.md
+
+Project context for AI assistants:
+
+```markdown
+# Project Name
+
+Brief description.
+
+## Quick Reference
+\`\`\`bash
+command1  # What it does
+command2  # What it does
+\`\`\`
+
+## Project Structure
+[Concise overview]
+
+## Patterns
+[Code conventions used]
+
+## Development
+[How to run/test]
+```
+
+---
+
+## Keep Docs Current
+
+```
+- Update FEATURES.md when shipping
+- Update ROADMAP.md when planning
+- Update ARCHITECTURE.md on major changes
+- Review quarterly for staleness
+```
+
+---
+
+*Template. Adapt structure to your project size.*

crucible/knowledge/principles/ERROR_HANDLING.md

@@ -0,0 +1,157 @@
+---
+name: Error Handling
+description: Result types, error boundaries, no silent failures
+triggers: [errors, exceptions, error-handling, try-catch]
+type: principle
+assertions: error-handling.yaml
+---
+
+# Error Handling Principles
+
+---
+
+## Result Types
+
+Return errors as values instead of throwing exceptions.
+
+```typescript
+// Throwing (invisible control flow)
+const getUser = (id: UserId): User => {
+  const user = db.find(id);
+  if (!user) throw new Error('Not found');
+  return user;
+}
+
+// Result type (explicit, type-safe)
+type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
+
+const getUser = (id: UserId): Result<User, 'NOT_FOUND' | 'DB_ERROR'> => {
+  try {
+    const user = db.find(id);
+    if (!user) return { ok: false, error: 'NOT_FOUND' };
+    return { ok: true, value: user };
+  } catch (e) {
+    return { ok: false, error: 'DB_ERROR' };
+  }
+}
+```
+
+---
+
+## Caller Handles Errors
+
+```typescript
+const result = await getUser(id);
+if (!result.ok) {
+  // Handle error
+  return;
+}
+// result.value is typed as User
+```
+
+---
+
+## Typed Errors
+
+```typescript
+// String errors (no structure, no exhaustiveness checking)
+throw new Error('Something went wrong');
+
+// Typed errors (structured, exhaustive)
+type TipError =
+  | { type: 'PAGE_NOT_FOUND' }
+  | { type: 'AMOUNT_TOO_SMALL'; minimum: Cents }
+  | { type: 'AMOUNT_TOO_LARGE'; maximum: Cents }
+  | { type: 'PAYMENT_FAILED'; reason: string };
+
+const handleError = (error: TipError) => {
+  switch (error.type) {
+    case 'PAGE_NOT_FOUND':
+      return 'Page not found';
+    case 'AMOUNT_TOO_SMALL':
+      return `Minimum amount is ${error.minimum}`;
+    // TypeScript ensures all cases handled
+  }
+};
+```
+
+---
+
+## When to Throw
+
+Exceptions are for truly exceptional cases:
+
+```
+Throw for:
+├── Out of memory
+├── Network unreachable
+├── Programmer errors (assertions, invariant violations)
+├── API boundaries (convert Result → HTTP status)
+
+Return Result for:
+├── Business logic ("user not found" is expected)
+├── Validation errors
+├── Anything the caller should handle
+```
+
+---
+
+## Python Pattern
+
+```python
+from dataclasses import dataclass
+from typing import Union
+
+@dataclass(frozen=True)
+class Ok[T]:
+    value: T
+
+@dataclass(frozen=True)
+class Err[E]:
+    error: E
+
+Result = Union[Ok[T], Err[E]]
+
+def get_user(user_id: str) -> Result[User, str]:
+    user = db.find(user_id)
+    if not user:
+        return Err("NOT_FOUND")
+    return Ok(user)
+```
+
+---
+
+## Error Messages
+
+```typescript
+// Vague
+throw new Error('Failed');
+
+// Actionable
+throw new Error(`Failed to fetch user ${userId}: connection timeout after 5000ms`);
+```
+
+---
+
+## Logging Errors
+
+```typescript
+// Silent failure (avoid)
+try {
+  await riskyOperation();
+} catch (e) {
+  // nothing
+}
+
+// Log at minimum
+try {
+  await riskyOperation();
+} catch (e) {
+  log.error('riskyOperation failed', { error: e });
+  // Then decide: rethrow, return default, or return error
+}
+```
+
+---
+
+*Template. Adapt to your needs.*

crucible/knowledge/principles/FP.md

@@ -0,0 +1,162 @@
+---
+name: Functional Programming
+description: Immutability, pure functions, composition patterns
+triggers: [functional, fp, immutable, pure-functions]
+type: preference
+---
+
+# Functional Programming Principles
+
+---
+
+## Core Concepts
+
+```
+FP characteristics:
+├── Pure functions (same input → same output)
+├── Immutable data structures
+├── Functions as first-class values
+├── Composition over inheritance
+└── Side effects isolated to boundaries
+
+Use OOP when:
+├── Modeling stateful entities
+├── Complex state machines
+├── Framework requires it
+```
+
+---
+
+## Pure Functions
+
+Same input produces same output. No side effects.
+
+```typescript
+// Pure: No state access, no external calls
+function calculateFee(amount: Cents): Cents {
+  return Math.round(amount * 0.01) as Cents;
+}
+
+// Impure: Reads external state
+function calculateFee(amount: Cents): Cents {
+  return Math.round(amount * config.feeRate) as Cents;
+}
+```
+
+---
+
+## Immutability
+
+```typescript
+// Mutation (avoid)
+const addItem = (items: Item[], newItem: Item) => {
+  items.push(newItem); // Mutates original
+  return items;
+}
+
+// Immutable (prefer)
+const addItem = (items: Item[], newItem: Item): Item[] => {
+  return [...items, newItem]; // New array
+}
+```
+
+**In Python:**
+```python
+@dataclass(frozen=True)
+class User:
+    id: str
+    email: str
+```
+
+---
+
+## Composition Over Inheritance
+
+```typescript
+// Inheritance (rigid hierarchy)
+class Animal { }
+class Dog extends Animal { }
+class ServiceDog extends Dog { }
+
+// Composition (flexible)
+const withLogging = (fn) => (...args) => {
+  console.log('Called with:', args);
+  return fn(...args);
+};
+
+const withRetry = (fn, attempts = 3) => async (...args) => {
+  for (let i = 0; i < attempts; i++) {
+    try { return await fn(...args); }
+    catch (e) { if (i === attempts - 1) throw e; }
+  }
+};
+
+// Compose behaviors
+const resilientFetch = withRetry(withLogging(fetch));
+```
+
+---
+
+## Functions vs Classes
+
+```typescript
+// Class-based
+class TipService {
+  private db: Database;
+  constructor(db: Database) { this.db = db; }
+  async createTip(data: TipData) { ... }
+}
+
+// Function-based
+const createTip = (db: Database, data: TipData): Promise<Result<Tip, TipError>> => { ... }
+
+// Factory for grouping related functions
+const createTipService = (db: Database) => ({
+  create: (data: TipData) => createTip(db, data),
+  getByPage: (pageId: PageId) => getTipsByPage(db, pageId),
+});
+```
+
+---
+
+## Data Transformations
+
+Pipelines over loops:
+
+```typescript
+// Imperative
+const results = [];
+for (const user of users) {
+  if (user.isActive) {
+    results.push(user.email);
+  }
+}
+
+// Declarative
+const activeEmails = users
+  .filter(user => user.isActive)
+  .map(user => user.email);
+```
+
+---
+
+## Side Effects at the Edges
+
+Push side effects to the boundaries:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  EDGES (side effects)                                    │
+│  HTTP handlers, database calls, external APIs           │
+└───────────────────────────┬─────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────┐
+│  CORE (pure)                                             │
+│  Business logic, calculations, transformations          │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+*Template. Adapt to your needs.*

crucible/knowledge/principles/GITIGNORE.md

@@ -0,0 +1,218 @@
+---
+name: Gitignore Patterns
+description: What to exclude from version control
+triggers: [gitignore, git, secrets]
+type: pattern
+---
+
+# Gitignore Principles
+
+Defense-in-depth for preventing secret commits.
+
+---
+
+## Structure
+
+Organize by category with clear headers:
+
+```gitignore
+# ============================================================================
+# SECRETS & SENSITIVE FILES (NEVER COMMIT)
+# ============================================================================
+
+# Environment files
+.env
+.env.*
+!.env.example
+
+# Private keys & certificates
+*.pem
+*.key
+*.p12
+```
+
+---
+
+## Secrets (Critical)
+
+### Environment Files
+
+```gitignore
+.env
+.env.*
+*.env
+*.env.*
+!.env.example
+!.env.*.example
+.envrc
+.envrc.*
+*.local
+```
+
+### Private Keys
+
+```gitignore
+*.pem
+*.key
+*.p12
+*.pfx
+*.jks
+*.crt
+id_rsa*
+id_ed25519*
+*.gpg
+*.asc
+```
+
+### Credentials
+
+```gitignore
+credentials.json
+secrets.json
+service-account*.json
+*-keyfile.json
+*.secret
+*.credentials
+application_default_credentials.json
+```
+
+### Cloud Configs
+
+```gitignore
+.aws/
+.gcloud/
+.azure/
+*.tfstate
+*.tfvars
+```
+
+---
+
+## Paranoid Mode
+
+Catch-all patterns for defense-in-depth:
+
+```gitignore
+# Anything with "secret" in the name
+*secret*
+*SECRET*
+!hooks/*-secrets.sh  # Allow hook scripts
+
+# Anything with "password" in the name
+*password*
+*PASSWORD*
+
+# Anything with "credential" in the name
+*credential*
+*CREDENTIAL*
+
+# Anything with "private" in the name
+*_private.*
+*.private.*
+```
+
+---
+
+## OS & Editor
+
+```gitignore
+# macOS
+.DS_Store
+._*
+
+# Windows
+Thumbs.db
+Desktop.ini
+
+# IDEs (allow shared settings)
+.vscode/
+!.vscode/settings.json
+!.vscode/extensions.json
+.idea/
+
+# Vim
+*.swp
+*.swo
+```
+
+---
+
+## Dependencies by Language
+
+```gitignore
+# Node
+node_modules/
+.pnpm-store/
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Go
+vendor/
+
+# Rust
+target/
+```
+
+---
+
+## Build & Test Output
+
+```gitignore
+dist/
+build/
+out/
+coverage/
+htmlcov/
+.coverage
+*.log
+```
+
+---
+
+## Tool-Specific
+
+```gitignore
+# Terraform (SECRETS!)
+.terraform/
+*.tfstate*
+*.tfvars
+
+# Docker
+docker-compose.override.yml
+
+# Kubernetes
+*.kubeconfig
+*-secret.yaml
+```
+
+---
+
+## Anti-patterns
+
+```gitignore
+# Bad: too broad
+*
+
+# Bad: no exceptions for examples
+.env*
+
+# Bad: missing paranoid patterns
+# (relies only on specific patterns)
+
+# Bad: no structure
+.env
+node_modules
+*.log
+.DS_Store
+```
+
+---
+
+*Layer with pre-commit hooks for defense-in-depth.*