@softspark/ai-toolkit 1.0.0

package/app/skills/testing-patterns/reference/python-pytest.md

@@ -0,0 +1,228 @@
+# Python Pytest Patterns
+
+## Fixtures
+
+### Basic Fixture
+
+```python
+import pytest
+
+@pytest.fixture
+def sample_document():
+    """Sample document for testing."""
+    return {
+        "path": "kb/test/doc.md",
+        "title": "Test Document",
+        "content": "Test content"
+    }
+
+def test_process_document(sample_document):
+    result = process(sample_document)
+    assert result.title == "Test Document"
+```
+
+### Async Fixture
+
+```python
+import pytest
+import httpx
+
+@pytest.fixture
+async def async_client(app):
+    """Create async HTTP client for testing."""
+    async with httpx.AsyncClient(app=app, base_url="http://test") as client:
+        yield client
+
+@pytest.mark.asyncio
+async def test_api_endpoint(async_client):
+    response = await async_client.get("/health")
+    assert response.status_code == 200
+```
+
+### Scoped Fixtures
+
+```python
+@pytest.fixture(scope="module")
+def database():
+    """Database connection reused across module."""
+    db = create_database()
+    yield db
+    db.close()
+
+@pytest.fixture(scope="session")
+def config():
+    """Configuration reused across entire session."""
+    return load_config()
+```
+
+## Mocking
+
+### Basic Mock
+
+```python
+from unittest.mock import Mock, patch
+
+def test_with_mock():
+    mock_client = Mock()
+    mock_client.search.return_value = [{"id": 1}]
+
+    result = function_using_client(mock_client)
+
+    mock_client.search.assert_called_once_with("query")
+    assert len(result) == 1
+```
+
+### Patch Decorator
+
+```python
+@patch("module.external_api")
+def test_with_patch(mock_api):
+    mock_api.return_value = {"data": "mocked"}
+
+    result = function_calling_api()
+
+    assert result == {"data": "mocked"}
+```
+
+### Async Mock
+
+```python
+from unittest.mock import AsyncMock
+
+@pytest.mark.asyncio
+async def test_async_function():
+    mock_client = AsyncMock()
+    mock_client.fetch.return_value = {"result": "data"}
+
+    result = await async_function(mock_client)
+
+    mock_client.fetch.assert_awaited_once()
+```
+
+### pytest-mock (Recommended)
+
+```python
+def test_with_mocker(mocker):
+    mock_client = mocker.patch("module.Client")
+    mock_client.return_value.search.return_value = []
+
+    result = search_function()
+
+    assert result == []
+```
+
+## Parametrization
+
+```python
+@pytest.mark.parametrize("input_val,expected", [
+    ("hello", "HELLO"),
+    ("world", "WORLD"),
+    ("test", "TEST"),
+])
+def test_uppercase(input_val, expected):
+    assert input_val.upper() == expected
+
+@pytest.mark.parametrize("query,limit,expected_count", [
+    ("test", 5, 5),
+    ("test", 10, 10),
+    ("", 5, 0),
+])
+def test_search_with_params(query, limit, expected_count):
+    results = search(query, limit)
+    assert len(results) <= expected_count
+```
+
+## Exception Testing
+
+```python
+def test_raises_value_error():
+    with pytest.raises(ValueError, match="Invalid input"):
+        function_that_raises(None)
+
+def test_raises_any_exception():
+    with pytest.raises(Exception):
+        risky_function()
+```
+
+## Markers
+
+```python
+@pytest.mark.slow
+def test_slow_operation():
+    """Marked as slow, can be skipped with -m 'not slow'."""
+    pass
+
+@pytest.mark.skip(reason="Not implemented yet")
+def test_future_feature():
+    pass
+
+@pytest.mark.skipif(sys.version_info < (3, 10), reason="Requires Python 3.10+")
+def test_new_feature():
+    pass
+
+@pytest.mark.xfail(reason="Known bug #123")
+def test_known_bug():
+    pass
+```
+
+## conftest.py
+
+```python
+# tests/conftest.py
+import pytest
+
+@pytest.fixture
+def app():
+    """Create test application."""
+    from app import create_app
+    return create_app(testing=True)
+
+@pytest.fixture
+def mock_llm(mocker):
+    """Mock LLM client for all tests."""
+    return mocker.patch("scripts.llm_client.LLMClient")
+```
+
+## Running Tests
+
+**Direct execution:**
+```bash
+# All tests
+pytest tests/
+
+# With coverage
+pytest --cov=src --cov-report=term-missing
+
+# Specific file
+pytest tests/unit/test_search_core.py
+
+# By marker
+pytest -m "not slow"
+
+# Verbose with print output
+pytest -v -s
+
+# Failed tests only
+pytest --lf
+```
+
+**Docker execution (if containerized):**
+```bash
+# All tests
+docker exec {app-container} pytest tests/
+
+# With coverage
+docker exec {app-container} pytest --cov=src --cov-report=term-missing
+
+# Specific file
+docker exec {app-container} pytest tests/unit/test_search_core.py
+
+# By marker
+docker exec {app-container} pytest -m "not slow"
+
+# Verbose with print output
+docker exec {app-container} pytest -v -s
+
+# Failed tests only
+docker exec {app-container} pytest --lf
+```

package/app/skills/testing-patterns/reference/typescript-vitest.md

@@ -0,0 +1,50 @@
+# TypeScript Vitest/Jest Patterns
+
+## Basic Test
+
+```typescript
+import { describe, it, expect, vi } from "vitest";
+
+describe("UserService", () => {
+  it("creates user with valid data", async () => {
+    const mockRepo = { create: vi.fn().mockResolvedValue({ id: "1", name: "Test" }) };
+    const service = new UserService(mockRepo);
+    const user = await service.create({ name: "Test", email: "t@t.com" });
+    expect(user.id).toBe("1");
+    expect(mockRepo.create).toHaveBeenCalledOnce();
+  });
+});
+```
+
+## React Testing Library
+
+```tsx
+import { render, screen, fireEvent } from "@testing-library/react";
+
+test("button click increments counter", () => {
+  render(<Counter />);
+  fireEvent.click(screen.getByRole("button"));
+  expect(screen.getByText("Count: 1")).toBeInTheDocument();
+});
+```
+
+## Mocking
+
+```typescript
+// Module mock
+vi.mock("./api", () => ({ fetchUsers: vi.fn().mockResolvedValue([]) }));
+
+// Spy
+const spy = vi.spyOn(service, "save");
+await service.process(data);
+expect(spy).toHaveBeenCalledWith(data);
+```
+
+## Running
+
+```bash
+npx vitest run                    # All tests
+npx vitest run --coverage         # With coverage
+npx vitest run src/utils.test.ts  # Specific file
+npx vitest --watch                # Watch mode
+```

package/app/skills/triage-issue/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: triage-issue
+description: "Triage a bug by deeply exploring the codebase for root cause, then create a GitHub issue with a TDD-based fix plan. Mostly hands-off — minimal user interaction. Use when user reports a bug, wants to investigate an issue, mentions triage, or wants a fix plan."
+user-invocable: true
+effort: high
+argument-hint: "[bug description or symptom]"
+agent: debugger
+context: fork
+allowed-tools: Read, Grep, Glob, Bash, Agent
+---
+
+# Triage Issue
+
+$ARGUMENTS
+
+Investigate a bug, find root cause, and create a GitHub issue with a TDD fix plan. Mostly hands-off.
+
+## Usage
+
+```
+/triage-issue [bug description or symptom]
+```
+
+## What This Command Does
+
+1. **Captures** problem description (ONE question max)
+2. **Explores** codebase deeply for root cause
+3. **Identifies** fix approach
+4. **Designs** TDD fix plan (RED→GREEN cycles)
+5. **Creates** GitHub issue via `gh issue create`
+
+## Process
+
+### 1. Capture the Problem
+
+Get brief description. If not provided, ask ONE question: "What's the problem you're seeing?"
+
+Do NOT ask follow-up questions. Start investigating immediately.
+
+### 2. Explore and Diagnose
+
+Use Agent (subagent_type=Explore) to deeply investigate:
+
+| Target | What to look for |
+|--------|-----------------|
+| Manifestation | Where the bug appears (entry points, UI, API) |
+| Code path | Trace the flow from trigger to symptom |
+| Root cause | Why it fails (not just the symptom) |
+| Related code | Similar patterns, adjacent modules, existing tests |
+| Recent changes | `git log` on relevant files |
+| Working patterns | Similar code elsewhere that works correctly |
+
+### 3. Identify Fix Approach
+
+Determine:
+- Minimal change to fix root cause
+- Affected modules/interfaces
+- Behaviors to verify via tests
+- Classification: regression, missing feature, or design flaw
+
+### 4. Design TDD Fix Plan
+
+Ordered list of RED→GREEN cycles. Each cycle is one vertical slice:
+
+- **RED**: Specific test capturing broken/missing behavior
+- **GREEN**: Minimal code change to pass that test
+
+Rules:
+- Tests verify behavior through public interfaces
+- One test at a time, vertical slices
+- Tests must survive internal refactors
+- Describe behaviors and contracts, not internal structure
+
+### 5. Create GitHub Issue
+
+Use `gh issue create` with template below. Share URL immediately.
+
+## Issue Template
+
+<issue-template>
+
+## Problem
+
+- What happens (actual behavior)
+- What should happen (expected behavior)
+- How to reproduce
+
+## Root Cause Analysis
+
+What was found during investigation:
+- The code path involved
+- Why the current code fails
+- Contributing factors
+
+Do NOT include file paths, line numbers, or implementation details. Describe modules, behaviors, and contracts.
+
+## TDD Fix Plan
+
+1. **RED**: Write test that [expected behavior]
+   **GREEN**: [Minimal change to pass]
+
+2. **RED**: Write test that [next behavior]
+   **GREEN**: [Minimal change to pass]
+
+**REFACTOR**: [Cleanup after all tests pass]
+
+## Acceptance Criteria
+
+- [ ] Criterion 1
+- [ ] All new tests pass
+- [ ] Existing tests still pass
+
+</issue-template>
+
+## Rules
+
+- Minimal user interaction — investigate autonomously
+- No file paths or line numbers in the issue (durability)
+- TDD plan uses vertical slices, not horizontal
+- File immediately — don't ask for review

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

@@ -0,0 +1,256 @@
+---
+name: typescript-patterns
+description: "Loaded when user asks about TypeScript patterns or type safety"
+effort: medium
+user-invocable: false
+---
+
+# TypeScript/JavaScript Patterns
+
+## TypeScript Configuration
+
+### Strict tsconfig.json
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "exactOptionalPropertyTypes": true,
+    "moduleResolution": "bundler",
+    "module": "ESNext",
+    "target": "ES2022",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+## ESLint + Prettier
+
+```json
+// .eslintrc.json (flat config recommended for new projects)
+{
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended-type-checked",
+    "prettier"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "project": "./tsconfig.json"
+  },
+  "rules": {
+    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
+    "@typescript-eslint/no-floating-promises": "error",
+    "@typescript-eslint/no-misused-promises": "error"
+  }
+}
+```
+
+## React Patterns
+
+### Functional Component
+```tsx
+interface UserCardProps {
+  user: User;
+  onSelect?: (id: string) => void;
+}
+
+export function UserCard({ user, onSelect }: UserCardProps) {
+  const handleClick = useCallback(() => {
+    onSelect?.(user.id);
+  }, [user.id, onSelect]);
+
+  return (
+    <div onClick={handleClick} role="button" tabIndex={0}>
+      <h3>{user.name}</h3>
+      <p>{user.email}</p>
+    </div>
+  );
+}
+```
+
+### Custom Hook
+```tsx
+function useAsync<T>(fn: () => Promise<T>, deps: unknown[]) {
+  const [state, setState] = useState<{
+    data: T | null;
+    error: Error | null;
+    loading: boolean;
+  }>({ data: null, error: null, loading: true });
+
+  useEffect(() => {
+    let cancelled = false;
+    setState(prev => ({ ...prev, loading: true }));
+    fn()
+      .then(data => { if (!cancelled) setState({ data, error: null, loading: false }); })
+      .catch(error => { if (!cancelled) setState({ data: null, error, loading: false }); });
+    return () => { cancelled = true; };
+  }, deps);
+
+  return state;
+}
+```
+
+### Context Pattern
+```tsx
+interface AuthContextType {
+  user: User | null;
+  login: (credentials: Credentials) => Promise<void>;
+  logout: () => void;
+}
+
+const AuthContext = createContext<AuthContextType | null>(null);
+
+export function useAuth() {
+  const context = useContext(AuthContext);
+  if (!context) throw new Error("useAuth must be within AuthProvider");
+  return context;
+}
+```
+
+## Next.js App Router
+
+### Server Component (default)
+```tsx
+// app/users/page.tsx
+export default async function UsersPage() {
+  const users = await db.user.findMany();
+  return <UserList users={users} />;
+}
+```
+
+### Server Action
+```tsx
+"use server";
+
+import { revalidatePath } from "next/cache";
+
+export async function createUser(formData: FormData) {
+  const name = formData.get("name") as string;
+  await db.user.create({ data: { name } });
+  revalidatePath("/users");
+}
+```
+
+## Node.js/Express Patterns
+
+### Type-safe Route Handler
+```typescript
+import { Router, Request, Response } from "express";
+import { z } from "zod";
+
+const CreateUserSchema = z.object({
+  name: z.string().min(1).max(100),
+  email: z.string().email(),
+});
+
+router.post("/users", async (req: Request, res: Response) => {
+  const result = CreateUserSchema.safeParse(req.body);
+  if (!result.success) {
+    return res.status(400).json({ errors: result.error.flatten() });
+  }
+  const user = await userService.create(result.data);
+  res.status(201).json(user);
+});
+```
+
+## State Management
+
+### Zustand Store
+```typescript
+import { create } from "zustand";
+
+interface CartStore {
+  items: CartItem[];
+  addItem: (item: CartItem) => void;
+  removeItem: (id: string) => void;
+  total: () => number;
+}
+
+export const useCartStore = create<CartStore>((set, get) => ({
+  items: [],
+  addItem: (item) => set((state) => ({ items: [...state.items, item] })),
+  removeItem: (id) => set((state) => ({ items: state.items.filter(i => i.id !== id) })),
+  total: () => get().items.reduce((sum, item) => sum + item.price, 0),
+}));
+```
+
+## Type-safe API (tRPC / Zod)
+
+### Zod Schema Validation
+```typescript
+import { z } from "zod";
+
+export const UserSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(1).max(100),
+  email: z.string().email(),
+  role: z.enum(["admin", "user", "guest"]),
+  createdAt: z.coerce.date(),
+});
+
+export type User = z.infer<typeof UserSchema>;
+```
+
+## Error Handling
+
+```typescript
+class AppError extends Error {
+  constructor(
+    message: string,
+    public statusCode: number = 500,
+    public code: string = "INTERNAL_ERROR"
+  ) {
+    super(message);
+    this.name = "AppError";
+  }
+}
+
+// Result pattern (no exceptions)
+type Result<T, E = Error> =
+  | { success: true; data: T }
+  | { success: false; error: E };
+
+function parseUser(raw: unknown): Result<User> {
+  const result = UserSchema.safeParse(raw);
+  if (result.success) return { success: true, data: result.data };
+  return { success: false, error: new Error(result.error.message) };
+}
+```
+
+## Testing with Vitest
+
+```typescript
+import { describe, it, expect, vi } from "vitest";
+
+describe("UserService", () => {
+  it("creates user with valid data", async () => {
+    const mockRepo = { create: vi.fn().mockResolvedValue({ id: "1", name: "Test" }) };
+    const service = new UserService(mockRepo);
+    const user = await service.create({ name: "Test", email: "t@t.com" });
+    expect(user.id).toBe("1");
+    expect(mockRepo.create).toHaveBeenCalledOnce();
+  });
+});
+```
+
+## Anti-Patterns
+- `any` type usage (use `unknown` and narrow)
+- Non-null assertions `!` without checks
+- `as` type casting instead of type guards
+- Mutable state in React (use immutable updates)
+- Missing error boundaries in React
+- Barrel exports that break tree-shaking