@softspark/ai-toolkit 1.0.0

package/app/skills/mcp-patterns/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: mcp-patterns
+description: "Loaded when user asks about MCP servers or tool protocol design"
+effort: medium
+user-invocable: false
+---
+
+# MCP Patterns Skill
+
+## MCP Specification (2025-06-18)
+
+### Core Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **Server** | Exposes tools, resources, prompts to clients |
+| **Client** | Connects to servers, invokes tools |
+| **Transport** | Communication layer (stdio, HTTP, SSE) |
+| **Tool** | Executable function with JSON Schema |
+| **Resource** | Read-only data (files, URLs) |
+| **Prompt** | Reusable prompt template |
+
+---
+
+## Tool Definition Pattern
+
+```typescript
+// TypeScript with @modelcontextprotocol/sdk
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [{
+    name: "search_kb",
+    description: "Search the knowledge base",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Search query"
+        },
+        limit: {
+          type: "number",
+          description: "Max results",
+          default: 10
+        }
+      },
+      required: ["query"]
+    },
+    annotations: {
+      readOnlyHint: true,      // Doesn't modify state
+      idempotentHint: true,    // Same input = same output
+      openWorldHint: false     // Bounded result set
+    }
+  }]
+}));
+```
+
+### Tool Annotations
+
+| Annotation | Meaning | Use When |
+|------------|---------|----------|
+| `readOnlyHint` | No side effects | Read operations |
+| `destructiveHint` | Deletes/modifies data | Write operations |
+| `idempotentHint` | Safe to retry | GET-like operations |
+| `openWorldHint` | Results may change | External API calls |
+
+---
+
+## Transport Patterns
+
+### 1. stdio (Default)
+
+```typescript
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+### 2. HTTP with SSE
+
+```python
+# FastAPI implementation
+from fastapi import FastAPI
+from sse_starlette.sse import EventSourceResponse
+
+app = FastAPI()
+
+@app.get("/mcp/sse")
+async def sse_endpoint():
+    async def event_generator():
+        while True:
+            # Yield MCP events
+            yield {"event": "message", "data": json.dumps(response)}
+    return EventSourceResponse(event_generator())
+
+@app.post("/mcp")
+async def jsonrpc_endpoint(request: Request):
+    body = await request.json()
+    response = await handle_jsonrpc(body)
+    return JSONResponse(response)
+```
+
+### 3. Streamable HTTP (Modern)
+
+Single `/mcp` endpoint handling GET (SSE) and POST (JSON-RPC):
+
+```python
+@app.api_route("/mcp", methods=["GET", "POST"])
+async def mcp_endpoint(request: Request):
+    if request.method == "GET":
+        # SSE streaming
+        return EventSourceResponse(stream_generator())
+    else:
+        # JSON-RPC
+        body = await request.json()
+        return JSONResponse(await handle_jsonrpc(body))
+```
+
+---
+
+## JSON-RPC 2.0 Pattern
+
+### Request Format
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "search_kb",
+    "arguments": {"query": "test", "limit": 5}
+  }
+}
+```
+
+### Response Format
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "content": [
+      {"type": "text", "text": "Search results..."}
+    ]
+  }
+}
+```
+
+### Error Format
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "error": {
+    "code": -32601,
+    "message": "Method not found"
+  }
+}
+```
+
+### Standard Error Codes
+| Code | Meaning |
+|------|---------|
+| -32700 | Parse error |
+| -32600 | Invalid request |
+| -32601 | Method not found |
+| -32602 | Invalid params |
+| -32603 | Internal error |
+
+---
+
+## Completion Support
+
+Enable intelligent argument suggestions:
+
+```typescript
+server.setRequestHandler(CompletionCompleteRequestSchema, async (request) => {
+  const { argument } = request.params;
+
+  if (argument.name === "service") {
+    return {
+      completion: {
+        values: ["nginx", "postgresql", "redis", "qdrant"],
+        hasMore: false
+      }
+    };
+  }
+
+  return { completion: { values: [], hasMore: false } };
+});
+```
+
+---
+
+## Session Management
+
+```typescript
+// Generate secure session ID
+const sessionId = crypto.randomUUID();
+
+// Validate Origin header
+const allowedOrigins = ["http://localhost:3000", "https://claude.ai"];
+if (!allowedOrigins.includes(request.headers.origin)) {
+  throw new Error("Invalid origin");
+}
+
+// Session storage (don't expose to client)
+const sessions = new Map<string, SessionData>();
+```
+
+---
+
+## Batching Support
+
+Handle multiple requests in single HTTP call:
+
+```python
+async def handle_jsonrpc(body):
+    if isinstance(body, list):
+        # Batch request
+        return [await process_single(req) for req in body]
+    else:
+        # Single request
+        return await process_single(body)
+```
+
+---
+
+## Best Practices
+
+### Security
+- [ ] Validate all inputs against JSON Schema
+- [ ] Validate Origin header
+- [ ] Implement rate limiting
+- [ ] Use environment variables for secrets
+- [ ] No secrets in logs or errors
+
+### Performance
+- [ ] Connection pooling
+- [ ] Response caching where appropriate
+- [ ] Streaming for large responses
+- [ ] Batch support for efficiency
+
+### Logging
+- [ ] Log to stderr (never stdout)
+- [ ] Structured JSON logs
+- [ ] Request/response tracing
+- [ ] Error logging with context
+
+### Documentation
+- [ ] Document all tools clearly
+- [ ] Include example usage
+- [ ] Version your API
+- [ ] Maintain changelog
+
+---
+
+## RAG-MCP MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `smart_query` | Primary search with auto-routing |
+| `hybrid_search_kb` | Raw vector + text search |
+| `get_document` | Full document content |
+| `crag_search` | Self-correcting search |
+| `multi_hop_search` | Complex reasoning |
+| `start_workflow` | Start agent workflow |
+| `get_workflow_status` | Check workflow progress |
+| `list_workflows` | List all workflows |
+| `cancel_workflow` | Cancel workflow |

package/app/skills/mem-search/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: mem-search
+description: "Search past coding sessions using natural language. Finds relevant observations, decisions, and context from previous work."
+effort: medium
+argument-hint: "[search query]"
+allowed-tools: Bash, Read
+user-invocable: true
+---
+
+# Search Session Memory
+
+Search the persistent memory database for past coding observations, decisions, and context.
+
+$ARGUMENTS
+
+## How It Works
+
+This skill queries the SQLite FTS5 full-text search index at `~/.ai-toolkit/memory.db` to find relevant observations from past sessions.
+
+## Instructions
+
+1. **Parse the search query** from `$ARGUMENTS`. If empty, prompt the user for a query.
+
+2. **Initialize the database** if it does not exist:
+   ```bash
+   python3 "$HOME/.ai-toolkit/hooks/../plugins/memory-pack/scripts/init_db.py" 2>/dev/null || true
+   ```
+
+3. **Run the FTS5 search** against the observations table:
+   ```bash
+   sqlite3 ~/.ai-toolkit/memory.db "
+     SELECT o.id, o.session_id, o.tool_name, o.content, o.created_at,
+            s.project_dir, s.summary
+     FROM observations_fts fts
+     JOIN observations o ON o.id = fts.rowid
+     LEFT JOIN sessions s ON s.session_id = o.session_id
+     WHERE observations_fts MATCH '<query>'
+     ORDER BY rank
+     LIMIT 10;
+   "
+   ```
+   Replace `<query>` with the user's search terms. Escape single quotes by doubling them.
+
+4. **Progressive disclosure** -- present results in two stages:
+
+   **Stage 1: Summary view** (show first)
+   ```markdown
+   ## Memory Search: "<query>"
+
+   Found N results across M sessions.
+
+   | # | Session | Project | Tool | Time | Preview |
+   |---|---------|---------|------|------|---------|
+   | 1 | abc123  | /path   | Edit | 2025-01-15 | First 80 chars... |
+   ```
+
+   **Stage 2: Detail view** (on request)
+   Show the full observation content, session summary, and related observations from the same session.
+
+5. **If no results found**, suggest:
+   - Trying broader search terms
+   - Checking if memory-pack hooks are installed
+   - Running `init-db.sh` if the database is missing
+
+## Query Tips
+
+- Use simple keywords: `mem-search database migration`
+- FTS5 supports prefix matching: `migrat*` matches "migration", "migrate"
+- Boolean operators: `database AND NOT test`
+- Column filters: `tool_name:Edit` to search only Edit tool observations

package/app/skills/migrate/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: migrate
+description: "Run database migrations with backup verification"
+effort: medium
+disable-model-invocation: true
+argument-hint: "[direction]"
+allowed-tools: Bash, Read
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "echo 'Reminder: ensure database backup exists before running migrations'"
+scripts:
+  - scripts/migration-status.py
+---
+
+# /migrate - Database Migration Workflow
+
+$ARGUMENTS
+
+## What This Command Does
+
+Create, run, or manage database migrations with auto-detection of the migration tool.
+
+## Project context
+
+- Migration tools: !`ls alembic.ini prisma/ database/migrations/ manage.py 2>/dev/null`
+
+## Migration Status Script
+
+Detect migration tool and report status:
+```bash
+python3 scripts/migration-status.py [directory]
+```
+
+Returns JSON with: `tool`, `config_file`, `migrations_dir`, `total_migrations`, `latest`, `commands{}` (status/create/upgrade/downgrade).
+
+## Auto-Detection
+
+| File Found | Tool | Commands |
+|------------|------|----------|
+| `alembic.ini` | Alembic | `alembic revision`, `alembic upgrade` |
+| `prisma/schema.prisma` | Prisma | `npx prisma migrate dev` |
+| `database/migrations/` + `artisan` | Laravel | `php artisan migrate` |
+| `manage.py` | Django | `python manage.py migrate` |
+| `flyway.conf` | Flyway | `flyway migrate` |
+| `drizzle.config.ts` | Drizzle | `npx drizzle-kit push` |
+
+## Workflow
+
+### Create New Migration
+1. Detect migration tool
+2. Generate migration from model/schema changes
+3. Review generated SQL
+4. Validate syntax
+
+### Run Migrations
+1. Show pending migrations
+2. Dry-run if supported (`--pretend`, `--sql`)
+3. Backup reminder
+4. Apply with user confirmation
+5. Verify success
+
+### Rollback
+1. Show last applied migration
+2. Confirm rollback scope
+3. Execute rollback
+4. Verify state
+
+## Safety Checks (MANDATORY)
+
+- [ ] Migration tested on development/staging first
+- [ ] Rollback path verified
+- [ ] No data loss in forward or backward direction
+- [ ] Large table operations use concurrent/online DDL
+- [ ] Backup exists or reminder given
+
+## Usage Examples
+
+```
+/migrate                     # Show migration status
+/migrate create add_users    # Create new migration
+/migrate run                 # Apply pending migrations
+/migrate rollback            # Rollback last migration
+/migrate status              # Show applied/pending migrations
+```
+
+## Reference Skill
+Use `migration-patterns` skill for zero-downtime strategies and best practices.

package/app/skills/migrate/scripts/migration-status.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""Detect migration tool and report status with commands reference.
+
+Scans a project directory for well-known migration configuration files
+(Alembic, Prisma, Laravel, Django, Drizzle) and returns a JSON object
+describing the detected tool, config file location, migrations
+directory, migration count, latest migration file, and command
+references for common operations.
+
+Usage::
+
+    python3 migration-status.py [directory]
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+TOOLS = {
+    "alembic": {
+        "config": "alembic.ini",
+        "migrations_dir": "alembic/versions",
+        "pattern": ".py",
+        "commands": {
+            "status": "alembic current",
+            "create": "alembic revision --autogenerate -m '<message>'",
+            "upgrade": "alembic upgrade head",
+            "downgrade": "alembic downgrade -1",
+        },
+    },
+    "prisma": {
+        "config": "prisma/schema.prisma",
+        "migrations_dir": "prisma/migrations",
+        "pattern": ".sql",
+        "commands": {
+            "status": "npx prisma migrate status",
+            "create": "npx prisma migrate dev --name <name>",
+            "upgrade": "npx prisma migrate deploy",
+            "downgrade": "npx prisma migrate resolve --rolled-back <name>",
+        },
+    },
+    "laravel": {
+        "config": "database/migrations",
+        "migrations_dir": "database/migrations",
+        "pattern": ".php",
+        "commands": {
+            "status": "php artisan migrate:status",
+            "create": "php artisan make:migration <name>",
+            "upgrade": "php artisan migrate",
+            "downgrade": "php artisan migrate:rollback --step=1",
+        },
+    },
+    "django": {
+        "config": "manage.py",
+        "migrations_dir": None,  # detected dynamically
+        "pattern": ".py",
+        "commands": {
+            "status": "python manage.py showmigrations",
+            "create": "python manage.py makemigrations",
+            "upgrade": "python manage.py migrate",
+            "downgrade": "python manage.py migrate <app> <previous>",
+        },
+    },
+    "drizzle": {
+        "config": "drizzle.config.ts",
+        "migrations_dir": "drizzle",
+        "pattern": ".sql",
+        "commands": {
+            "status": "npx drizzle-kit check",
+            "create": "npx drizzle-kit generate",
+            "upgrade": "npx drizzle-kit push",
+            "downgrade": "npx drizzle-kit drop",
+        },
+    },
+}
+
+
+def find_django_migrations(project_dir: Path) -> str | None:
+    """Find Django migration directories by looking for apps with migrations/.
+
+    Args:
+        project_dir: Root directory of the Django project.
+
+    Returns:
+        Relative path to the first discovered migrations directory, or
+        ``None`` if no Django app with migrations is found.
+    """
+    for item in project_dir.iterdir():
+        if item.is_dir() and (item / "migrations").is_dir():
+            mig_init = item / "migrations" / "__init__.py"
+            if mig_init.exists():
+                return str(item / "migrations")
+    return None
+
+
+def count_migrations(mig_dir: Path, pattern: str) -> tuple[int, str | None]:
+    """Count migration files and find the latest one.
+
+    Args:
+        mig_dir: Directory containing migration files.
+        pattern: File extension to match (e.g. ``".py"``, ``".sql"``).
+
+    Returns:
+        A tuple of ``(count, latest_filename)`` where *latest_filename*
+        is the name of the most recently modified migration, or ``None``
+        if no migrations exist.
+    """
+    if not mig_dir.is_dir():
+        return 0, None
+    files = sorted(
+        [f for f in mig_dir.iterdir() if f.suffix == pattern and f.name != "__init__.py"],
+        key=lambda p: p.stat().st_mtime,
+    )
+    return len(files), files[-1].name if files else None
+
+
+def detect(project_dir: Path) -> dict[str, object]:
+    """Detect migration tool and gather status.
+
+    Iterates through known migration tools and checks for their
+    configuration files. Returns the first match with tool name,
+    config location, migrations directory, file counts, and
+    command references.
+
+    Args:
+        project_dir: Root directory of the project to analyse.
+
+    Returns:
+        Dictionary with keys ``tool``, ``config_file``,
+        ``migrations_dir``, ``total_migrations``, ``latest``,
+        and ``commands``.
+    """
+    for tool_name, info in TOOLS.items():
+        config_path = project_dir / info["config"]
+        if tool_name == "laravel":
+            if not config_path.is_dir():
+                continue
+        elif tool_name == "drizzle":
+            # Also check .js variant
+            if not config_path.exists() and not (project_dir / "drizzle.config.js").exists():
+                continue
+        else:
+            if not config_path.exists():
+                continue
+
+        # Determine migrations directory
+        mig_dir_rel = info["migrations_dir"]
+        if tool_name == "django":
+            mig_dir_rel = find_django_migrations(project_dir)
+            if not mig_dir_rel:
+                mig_dir_rel = "<app>/migrations"
+
+        mig_dir = project_dir / mig_dir_rel if mig_dir_rel else None
+        total, latest = (0, None)
+        if mig_dir and mig_dir.is_dir():
+            total, latest = count_migrations(mig_dir, info["pattern"])
+
+        return {
+            "tool": tool_name,
+            "config_file": str(config_path.relative_to(project_dir)),
+            "migrations_dir": mig_dir_rel,
+            "total_migrations": total,
+            "latest": latest,
+            "commands": info["commands"],
+        }
+
+    return {
+        "tool": None,
+        "config_file": None,
+        "migrations_dir": None,
+        "total_migrations": 0,
+        "latest": None,
+        "commands": {},
+    }
+
+
+def main() -> None:
+    """Entry point: detect migration tool and print JSON result to stdout."""
+    project_dir = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else Path.cwd()
+    if not project_dir.is_dir():
+        print(json.dumps({"error": f"Not a directory: {project_dir}"}))
+        sys.exit(1)
+    try:
+        result = detect(project_dir)
+        result["project_dir"] = str(project_dir)
+        print(json.dumps(result, indent=2))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()