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

crucible/knowledge/loader.py

@@ -4,12 +4,96 @@ Knowledge follows the same cascade as skills:
 1. Project: .crucible/knowledge/
 2. User: ~/.claude/crucible/knowledge/
 3. Bundled: package knowledge/
+
+Knowledge files support frontmatter for better Claude Code integration:
+---
+name: Security Principles
+description: Core security principles for all code
+triggers: [security, auth, crypto]
+type: principle  # principle | pattern | preference
+assertions: security.yaml  # linked assertion file
+---
 """
 
+from dataclasses import dataclass, field
 from pathlib import Path
 
+import yaml
+
 from crucible.errors import Result, err, ok
 
+
+@dataclass(frozen=True)
+class KnowledgeMetadata:
+    """Metadata parsed from knowledge file frontmatter."""
+
+    name: str
+    description: str = ""
+    triggers: tuple[str, ...] = ()
+    type: str = "principle"  # principle, pattern, preference
+    assertions: str | None = None  # linked assertion file
+
+    @classmethod
+    def from_frontmatter(cls, data: dict, filename: str) -> "KnowledgeMetadata":
+        """Create metadata from parsed frontmatter dict."""
+        return cls(
+            name=data.get("name", filename.replace(".md", "").replace("_", " ").title()),
+            description=data.get("description", ""),
+            triggers=tuple(data.get("triggers", [])),
+            type=data.get("type", "principle"),
+            assertions=data.get("assertions"),
+        )
+
+
+@dataclass
+class KnowledgeFile:
+    """A knowledge file with metadata and content."""
+
+    filename: str
+    path: Path
+    source: str  # project, user, bundled
+    metadata: KnowledgeMetadata
+    content: str = field(repr=False)
+
+
+def parse_frontmatter(content: str, filename: str) -> tuple[KnowledgeMetadata, str]:
+    """Parse YAML frontmatter from knowledge file content.
+
+    Args:
+        content: Full file content
+        filename: Filename for default metadata
+
+    Returns:
+        Tuple of (metadata, content without frontmatter)
+    """
+    if not content.startswith("---"):
+        # No frontmatter, return defaults
+        return KnowledgeMetadata(name=filename.replace(".md", "").replace("_", " ").title()), content
+
+    # Find closing ---
+    lines = content.split("\n")
+    end_idx = None
+    for i, line in enumerate(lines[1:], 1):
+        if line.strip() == "---":
+            end_idx = i
+            break
+
+    if end_idx is None:
+        # Malformed frontmatter, treat as no frontmatter
+        return KnowledgeMetadata(name=filename.replace(".md", "").replace("_", " ").title()), content
+
+    # Parse YAML
+    frontmatter_text = "\n".join(lines[1:end_idx])
+    remaining_content = "\n".join(lines[end_idx + 1 :]).lstrip()
+
+    try:
+        data = yaml.safe_load(frontmatter_text) or {}
+        metadata = KnowledgeMetadata.from_frontmatter(data, filename)
+    except yaml.YAMLError:
+        metadata = KnowledgeMetadata(name=filename.replace(".md", "").replace("_", " ").title())
+
+    return metadata, remaining_content
+
 # Knowledge directories (same pattern as skills)
 KNOWLEDGE_BUNDLED = Path(__file__).parent / "principles"
 KNOWLEDGE_USER = Path.home() / ".claude" / "crucible" / "knowledge"
@@ -71,6 +155,77 @@ def get_all_knowledge_files() -> set[str]:
     return files
 
 
+def load_knowledge_with_metadata(filename: str) -> Result[KnowledgeFile, str]:
+    """Load a knowledge file with parsed metadata.
+
+    Args:
+        filename: Knowledge file name (e.g., "SECURITY.md")
+
+    Returns:
+        Result containing KnowledgeFile or error message
+    """
+    path, source = resolve_knowledge_file(filename)
+    if path is None:
+        return err(f"Knowledge file '{filename}' not found")
+
+    try:
+        raw_content = path.read_text()
+        metadata, content = parse_frontmatter(raw_content, filename)
+        return ok(
+            KnowledgeFile(
+                filename=filename,
+                path=path,
+                source=source,
+                metadata=metadata,
+                content=content,
+            )
+        )
+    except OSError as e:
+        return err(f"Failed to read '{filename}': {e}")
+
+
+def get_all_knowledge_metadata() -> list[tuple[str, KnowledgeMetadata]]:
+    """Get metadata for all knowledge files (for discovery/indexing).
+
+    Returns list of (filename, metadata) tuples. This is cheap - only parses
+    frontmatter, doesn't load full content into memory.
+    """
+    results: list[tuple[str, KnowledgeMetadata]] = []
+
+    for filename in sorted(get_all_knowledge_files()):
+        path, _ = resolve_knowledge_file(filename)
+        if path:
+            try:
+                # Read just enough to get frontmatter
+                content = path.read_text()
+                metadata, _ = parse_frontmatter(content, filename)
+                results.append((filename, metadata))
+            except OSError:
+                # Skip unreadable files
+                pass
+
+    return results
+
+
+def get_knowledge_by_trigger(trigger: str) -> list[str]:
+    """Get knowledge files that match a trigger.
+
+    Args:
+        trigger: Trigger to match (e.g., "security", "auth")
+
+    Returns:
+        List of matching filenames
+    """
+    matches: list[str] = []
+    trigger_lower = trigger.lower()
+
+    for filename, metadata in get_all_knowledge_metadata():
+        if trigger_lower in [t.lower() for t in metadata.triggers]:
+            matches.append(filename)
+
+    return matches
+
+
 def get_custom_knowledge_files() -> set[str]:
     """Get knowledge files from project and user directories only.
 
@@ -157,6 +312,37 @@ def load_principles(topic: str | None = None) -> Result[str, str]:
     return ok("\n\n---\n\n".join(content_parts))
 
 
+def get_linked_assertion_files(knowledge_files: set[str] | None = None) -> set[str]:
+    """Get assertion files linked to knowledge files.
+
+    Looks at the `assertions` field in knowledge frontmatter to find
+    linked assertion files that should be loaded.
+
+    Args:
+        knowledge_files: Specific knowledge files to check (if None, checks all)
+
+    Returns:
+        Set of assertion filenames to load
+    """
+    if knowledge_files is None:
+        knowledge_files = get_all_knowledge_files()
+
+    assertion_files: set[str] = set()
+
+    for filename in knowledge_files:
+        path, _ = resolve_knowledge_file(filename)
+        if path:
+            try:
+                content = path.read_text()
+                metadata, _ = parse_frontmatter(content, filename)
+                if metadata.assertions:
+                    assertion_files.add(metadata.assertions)
+            except OSError:
+                pass
+
+    return assertion_files
+
+
 def get_persona_section(persona: str, content: str) -> str | None:
     """
     Extract a specific persona section from the checklist content.

crucible/knowledge/principles/API_DESIGN.md

@@ -0,0 +1,176 @@
+---
+name: API Design
+description: REST conventions, versioning, pagination, error responses
+triggers: [api, rest, http, endpoints]
+type: pattern
+---
+
+# API Design Principles
+
+REST conventions, response shapes, and common patterns.
+
+---
+
+## REST Conventions
+
+```
+Nouns, not verbs:
+├── GET    /tips         ← List tips
+├── POST   /tips         ← Create tip
+├── GET    /tips/:id     ← Get single tip
+├── PUT    /tips/:id     ← Update tip (full)
+├── PATCH  /tips/:id     ← Update tip (partial)
+├── DELETE /tips/:id     ← Delete tip
+```
+
+---
+
+## Consistent Response Shapes
+
+```typescript
+// Success
+{ data: T }
+
+// Error
+{ error: { code: string, message: string } }
+
+// List (with pagination)
+{ data: T[], meta: { total: number, page: number, pageSize: number } }
+```
+
+---
+
+## HTTP Status Codes
+
+```
+200 OK           ← Success (GET, PUT, PATCH)
+201 Created      ← Resource created (POST)
+204 No Content   ← Success, no body (DELETE)
+400 Bad Request  ← Client error (validation)
+401 Unauthorized ← Not authenticated
+403 Forbidden    ← Authenticated but not allowed
+404 Not Found    ← Resource doesn't exist
+409 Conflict     ← State conflict
+422 Unprocessable← Validation failed
+429 Too Many     ← Rate limited
+500 Server Error ← Server fault
+```
+
+---
+
+## Rate Limiting
+
+```
+Headers to return:
+├── X-RateLimit-Limit: 100
+├── X-RateLimit-Remaining: 95
+├── X-RateLimit-Reset: 1609459200
+└── Retry-After: 60 (on 429)
+```
+
+---
+
+## Pagination
+
+Use bounded lists:
+
+```typescript
+// Request
+GET /tips?page=2&pageSize=20
+
+// Response
+{
+  data: [...],
+  meta: {
+    total: 150,
+    page: 2,
+    pageSize: 20,
+    totalPages: 8
+  }
+}
+```
+
+---
+
+## Versioning
+
+```
+For internal APIs (tRPC, same team):
+├── No explicit versioning
+├── Type system catches breakage
+└── Change and deploy together
+
+For public APIs (external consumers):
+├── Version in URL: /v1/tips
+├── Support N-1 version minimum
+├── Deprecation warnings before removal
+└── Breaking change = major version bump
+```
+
+---
+
+## Idempotency
+
+For operations that can be retried:
+
+```typescript
+// Not idempotent
+POST /payments
+{ amount: 100 }
+// Called twice = charged twice
+
+// Idempotent
+POST /payments
+{
+  amount: 100,
+  idempotencyKey: "user-123-order-456"
+}
+// Called twice = charged once
+```
+
+---
+
+## Error Responses
+
+```typescript
+// Vague
+{ error: "Something went wrong" }
+
+// Actionable
+{
+  error: {
+    code: "VALIDATION_ERROR",
+    message: "Invalid request",
+    details: [
+      { field: "email", message: "Must be a valid email" },
+      { field: "amount", message: "Must be positive" }
+    ]
+  }
+}
+```
+
+---
+
+## tRPC for Internal APIs
+
+Type-safe end-to-end:
+
+```typescript
+export const tipRouter = router({
+  create: protectedProcedure
+    .input(CreateTipSchema)
+    .mutation(({ input, ctx }) => {
+      return createTip(ctx.db, input);
+    }),
+
+  list: protectedProcedure
+    .input(z.object({ pageId: z.string() }))
+    .query(({ input }) => {
+      return getTipsByPage(input.pageId);
+    }),
+});
+```
+
+---
+
+*Template. Adapt to your needs.*

crucible/knowledge/principles/COMMITS.md

@@ -0,0 +1,127 @@
+---
+name: Commit Messages
+description: Conventional commits format and best practices
+triggers: [git, commits, version-control]
+type: pattern
+---
+
+# Commit Message Principles
+
+Semantic commits for readable history.
+
+---
+
+## Format
+
+```
+(type): description
+
+Body (optional)
+
+Co-Authored-By: Name <email>
+```
+
+---
+
+## Types
+
+| Type | Use When |
+|------|----------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `refactor` | Code restructure (no behavior change) |
+| `test` | Adding or updating tests |
+| `chore` | Build, deps, config changes |
+| `perf` | Performance improvement |
+| `style` | Formatting, whitespace |
+
+---
+
+## Good Examples
+
+```bash
+# Feature
+(feat): add pagination to tips endpoint
+
+# Bug fix
+(fix): handle empty response from Stripe webhook
+
+# Refactor
+(refactor): extract fee calculation to pure function
+
+# Docs
+(docs): add API authentication examples
+
+# Test
+(test): add integration tests for payment flow
+```
+
+---
+
+## Bad Examples
+
+```bash
+# Too vague
+fix stuff
+update code
+changes
+
+# Too long
+(feat): add a new endpoint for handling user authentication with OAuth2 and also add rate limiting and logging
+
+# Wrong type
+(feat): fix typo in README  # should be (docs) or (fix)
+```
+
+---
+
+## Commit Body
+
+For complex changes, add context:
+
+```bash
+(fix): prevent duplicate charges on retry
+
+Stripe webhook was being processed multiple times when
+the initial response timed out. Added idempotency check
+using the event ID.
+
+Closes #123
+```
+
+---
+
+## Atomic Commits
+
+One logical change per commit:
+
+```
+# Good: atomic commits
+(feat): add User model
+(feat): add user registration endpoint
+(test): add user registration tests
+
+# Bad: everything at once
+(feat): add user feature
+```
+
+---
+
+## Squashing
+
+For feature branches with messy history:
+
+```bash
+# Interactive rebase before merge
+git rebase -i main
+
+# Squash WIP commits into meaningful ones
+pick abc1234 (feat): add payment processing
+squash def5678 WIP
+squash ghi9012 fix tests
+```
+
+---
+
+*Template. Adapt format to your team's conventions.*

crucible/knowledge/principles/DATABASE.md

@@ -0,0 +1,138 @@
+---
+name: Database Patterns
+description: Migrations, indexing, query patterns, connection management
+triggers: [database, sql, postgres, mysql, migrations]
+type: pattern
+---
+
+# Database Principles
+
+---
+
+## Core Rules
+
+| Rule | Reason |
+|------|--------|
+| UUIDs for primary keys | No enumeration attacks, no auto-increment collisions |
+| Timestamps on everything | `created_at`, `updated_at` for debugging |
+| Soft delete when data matters | `deleted_at` instead of hard delete |
+| Amounts in cents | No floating point money (500 = $5.00) |
+| Encrypt sensitive data at rest | Defense in depth |
+
+---
+
+## Index Strategy
+
+```sql
+-- Every foreign key
+CREATE INDEX idx_tips_page_id ON tips(page_id);
+
+-- Everything you WHERE on
+CREATE INDEX idx_profiles_username ON user_profiles(username);
+
+-- Everything you ORDER BY
+CREATE INDEX idx_tips_created_at ON tips(created_at);
+
+-- Composite for common query patterns
+CREATE INDEX idx_tips_page_status ON tips(page_id, status);
+```
+
+---
+
+## Optimization Order
+
+```
+1. Indexes (90% of performance issues)
+2. Query design (N+1, unbounded selects)
+3. Connection pooling
+4. Read replicas
+5. Caching layer
+6. Sharding (rarely needed)
+```
+
+---
+
+## N+1 Queries
+
+```typescript
+// N+1 (1 query for pages + N queries for tips)
+const pages = await db.page.findMany();
+for (const page of pages) {
+  const tips = await db.tip.findMany({ where: { pageId: page.id } });
+}
+
+// Include (1 query with join)
+const pages = await db.page.findMany({
+  include: { tips: true }
+});
+```
+
+---
+
+## Naming Conventions
+
+```
+Tables:  plural, snake_case     → user_profiles, orders
+Columns: snake_case             → created_at, user_id
+Indexes: descriptive            → idx_tips_page_id
+```
+
+---
+
+## Migrations
+
+```
+├── One migration per change
+├── Migrations should be reversible
+├── Test migrations on production data (copy)
+├── Do not edit deployed migrations
+└── Separate schema changes from data migrations
+```
+
+---
+
+## Transactions
+
+```typescript
+// Atomic operations
+await db.$transaction(async (tx) => {
+  await tx.account.update({
+    where: { id: fromAccount },
+    data: { balance: { decrement: amount } }
+  });
+  await tx.account.update({
+    where: { id: toAccount },
+    data: { balance: { increment: amount } }
+  });
+});
+// Both succeed or both fail
+```
+
+---
+
+## Connection Pooling
+
+```
+├── Use connection pools (Prisma does this)
+├── Size pool based on: (cores * 2) + disk spindles
+├── Set connection timeout
+├── Monitor pool exhaustion
+```
+
+---
+
+## Query Safety
+
+Use parameterized queries:
+
+```typescript
+// SQL injection risk
+const query = `SELECT * FROM users WHERE id = '${userId}'`;
+
+// Parameterized (ORMs do this)
+const user = await db.user.findUnique({ where: { id: userId } });
+```
+
+---
+
+*Template. Adapt to your needs.*