claude-code-kit 0.7.0__py3-none-any.whl

claude_kit/_payload/rules/testing.md

@@ -0,0 +1,417 @@
+# Testing Standards
+
+All new code and modified code MUST have accompanying unit tests with a minimum **90% coverage** threshold across all metrics (or as defined by the project's coverage policy).
+
+## Coverage Thresholds (Enforced)
+
+| Metric | Minimum |
+|--------|---------|
+| Statements | 90% |
+| Branches | 90% |
+| Functions | 90% |
+| Lines | 90% |
+
+These thresholds should be configured in the project's test runner configuration and enforced via the test coverage command. **Do not lower them without justification.**
+
+## Stack-Specific Setup
+
+The project uses:
+- The project's test runner (check package.json/pyproject.toml/build config for the test framework)
+- The project's coverage provider
+- Testing libraries appropriate to the stack (component testing libraries for UI, mocking libraries, assertion libraries)
+
+Refer to the project's test configuration files for exact setup and command reference.
+
+## Commands
+
+Run the project's test commands:
+- Run all tests once
+- Run in watch mode during development
+- Run with coverage report (enforces coverage threshold)
+
+Check the project's package manager scripts or test runner documentation for exact commands.
+
+## File Organization
+
+Tests should mirror the source structure. Common patterns:
+
+**Option 1: Co-located tests**
+```
+src/
+├── module/
+│   ├── feature.ts
+│   └── feature.test.ts
+```
+
+**Option 2: Separate test directory**
+```
+src/
+├── module/
+│   └── feature.ts
+└── test/
+    └── module/
+        └── feature.test.ts
+```
+
+**Backend projects often use:**
+```
+backend/
+├── app/
+│   └── module/
+│       └── service.py
+└── tests/
+    └── module/
+        └── test_service.py
+```
+
+- Test file naming: `<source-file-name>.test.<ext>` or `test_<source-file-name>.<ext>`
+- Mirror the source directory structure
+- Test setup/fixtures in a dedicated setup file or conftest
+
+## What to Test
+
+### Always Test
+
+| Category | Examples |
+|----------|---------|
+| **Pure functions** | Formatters, validators, transformers, utility helpers |
+| **State management** | Store actions, state mutations, derived state, edge cases |
+| **Custom abstractions** | Custom hooks, decorators, middleware, utilities |
+| **Component/view rendering** | Renders without crashing, displays correct content based on inputs |
+| **User interactions** | Click handlers, form submissions, input changes |
+| **Conditional logic** | Loading, empty, error, and success states |
+| **Edge cases** | Null/undefined inputs, empty collections, boundary values |
+| **Accessibility** | Correct ARIA attributes, roles, labels (for UI components) |
+| **API contracts** | Request/response shapes, error handling, validation |
+| **Business logic** | Service layer functions, domain rules, calculations |
+
+### Never Test
+
+| Category | Why |
+|----------|-----|
+| Implementation details | Internal state values, private methods — test behavior, not internals |
+| Third-party libraries | Trust the library; test your usage, not the library itself |
+| Exact styling/CSS classes | Brittle, changes don't affect behavior |
+| Snapshot tests | Fragile, noisy diffs, false positives (use sparingly if at all) |
+| Type definitions | The type checker handles this at compile/build time |
+| Console output | Not user-visible behavior unless it's logging/monitoring specific |
+
+## Writing Tests
+
+### Test Structure
+
+**General pattern (language-agnostic concept):**
+```
+describe/group tests by module or feature
+  describe/group by function/class/component
+    setup/teardown hooks to reset state between tests
+    
+    test case: valid input produces expected output
+    test case: edge case handling
+    test case: error handling
+```
+
+**Example (JavaScript/TypeScript style):**
+```typescript
+import { describe, it, expect, beforeEach } from '<test-framework>';
+
+describe('ModuleName', () => {
+  describe('functionName', () => {
+    beforeEach(() => {
+      // Reset state between tests
+    });
+
+    it('returns expected value for valid input', () => {
+      expect(functionName('input')).toBe('expected');
+    });
+
+    it('handles edge case', () => {
+      expect(functionName('')).toBe('default');
+    });
+
+    it('throws for invalid input', () => {
+      expect(() => functionName(null)).toThrow();
+    });
+  });
+});
+```
+
+**Example (Python style):**
+```python
+import pytest
+
+class TestModuleName:
+    def setup_method(self):
+        # Reset state before each test
+        pass
+
+    def test_returns_expected_value_for_valid_input(self):
+        assert function_name('input') == 'expected'
+
+    def test_handles_edge_case(self):
+        assert function_name('') == 'default'
+
+    def test_raises_for_invalid_input(self):
+        with pytest.raises(ValueError):
+            function_name(None)
+```
+
+### Testing Pure Functions
+
+```typescript
+// Example: Utility functions
+describe('formatCurrency', () => {
+  it('formats positive numbers with currency symbol', () => {
+    expect(formatCurrency(1234.5)).toBe('$1,234.50');
+  });
+
+  it('handles zero', () => {
+    expect(formatCurrency(0)).toBe('$0.00');
+  });
+
+  it('handles negative numbers', () => {
+    expect(formatCurrency(-500)).toBe('-$500.00');
+  });
+});
+```
+
+### Testing State Management
+
+Test stores/state containers by:
+1. Verifying initial state
+2. Testing actions/mutations
+3. Testing derived/computed state
+4. Resetting state between tests
+
+```typescript
+// Example: Client-side state store
+describe('AppStore', () => {
+  beforeEach(() => {
+    // Reset store to initial state
+    store.reset();
+  });
+
+  it('has correct initial state', () => {
+    const state = store.getState();
+    expect(state.currentUser).toBeNull();
+  });
+
+  it('updates user via setUser action', () => {
+    store.setUser({ id: 1, name: 'Test' });
+    expect(store.getState().currentUser).toEqual({ id: 1, name: 'Test' });
+  });
+});
+```
+
+### Testing Components/Views
+
+For UI frameworks, test:
+1. Rendering with required props/inputs
+2. User interactions (clicks, form submissions)
+3. Conditional rendering (loading, empty, error states)
+4. Accessibility attributes
+
+```typescript
+// Example: UI component testing
+describe('ComponentName', () => {
+  it('renders with required props', () => {
+    render(<ComponentName title="Test" value={42} />);
+    expect(screen.getByText('Test')).toBeInTheDocument();
+    expect(screen.getByText('42')).toBeInTheDocument();
+  });
+
+  it('calls onClick when button is clicked', async () => {
+    const handleClick = mockFunction();
+    render(<ComponentName onClick={handleClick} />);
+    
+    await userInteraction.click(screen.getByRole('button'));
+    expect(handleClick).toHaveBeenCalledOnce();
+  });
+
+  it('shows empty state when no data', () => {
+    render(<ComponentName data={[]} />);
+    expect(screen.getByText(/no.*found/i)).toBeInTheDocument();
+  });
+});
+```
+
+### Testing API/Service Layer
+
+For backend services and API clients:
+
+```python
+# Example: Backend service testing
+class TestUserService:
+    async def test_create_user_with_valid_data(self, db_session):
+        payload = {"email": "test@example.com", "password": "secure123"}
+        user = await user_service.create_user(db_session, payload)
+        
+        assert user.id is not None
+        assert user.email == "test@example.com"
+        # Never leak sensitive fields in responses
+        assert not hasattr(user, 'password')
+    
+    async def test_create_user_duplicate_email_raises_conflict(self, db_session):
+        payload = {"email": "test@example.com", "password": "secure123"}
+        await user_service.create_user(db_session, payload)
+        
+        with pytest.raises(ConflictError):
+            await user_service.create_user(db_session, payload)
+```
+
+## Query/Selection Priority (UI Testing)
+
+When testing UI components, use the most accessible/semantic selector first:
+
+| Priority | Method | When |
+|----------|--------|------|
+| 1 | By role | Buttons, headings, links, form elements (semantic HTML) |
+| 2 | By label | Form inputs with labels |
+| 3 | By text content | Non-interactive text |
+| 4 | By current value | Form input values |
+| 5 | By test ID | Last resort — add `data-testid` or similar attribute |
+
+**Never query by CSS class, tag name, or DOM structure.** These are implementation details.
+
+## Mocking
+
+### Module/Import Mocks
+
+Mock external dependencies at module boundaries:
+
+```typescript
+// Mock an entire module
+mock('@/external/service');
+
+// Mock with custom implementation
+mock('@/lib/utils', () => ({
+  formatCurrency: mockFn((v: number) => `$${v}`),
+}));
+```
+
+```python
+# Mock with pytest/unittest
+from unittest.mock import patch, MagicMock
+
+@patch('app.external.service.make_api_call')
+def test_service_with_mocked_api(mock_api_call):
+    mock_api_call.return_value = {'status': 'ok'}
+    # test code
+```
+
+### State Store Mocks
+
+```typescript
+// Mock state container/store
+mock('@/stores/appStore');
+
+beforeEach(() => {
+  mockedStore.mockImplementation((selector) =>
+    selector({
+      currentUser: { id: 1, name: 'Test' },
+      logout: mockFn(),
+    })
+  );
+});
+```
+
+### Time/Timer Mocks
+
+For testing debouncing, throttling, or time-dependent behavior:
+
+```typescript
+beforeEach(() => {
+  useFakeTimers();
+});
+
+afterEach(() => {
+  useRealTimers();
+});
+
+it('debounces input', () => {
+  // trigger input
+  advanceTimersByTime(300);
+  // assert debounced result
+});
+```
+
+## Rules
+
+1. **Write tests for every new function, module, and component** — no exceptions
+2. **Run coverage checks before finishing work** — all metrics must meet the threshold
+3. **Test behavior, not implementation** — assert what the user/caller sees, not internal state
+4. **One assertion concept per test** — multiple assertions are fine if they test the same concept
+5. **Use descriptive test names** — `it('shows error message when form is invalid')` not `it('test 3')`
+6. **Mock at boundaries** — mock external APIs, stores, and I/O; not internal functions
+7. **Reset state between tests** — use setup/teardown hooks to clear mocks and reset state
+8. **No test interdependence** — each test must pass in isolation and in any order
+9. **Cover edge cases** — empty collections, null values, boundary numbers, long strings
+10. **Cover all branches** — if there's an `if/else`, test both paths; if there's a switch, test all cases
+11. **For multi-tenant systems** — test tenant/authorization scoping on every query/operation that should be scoped
+
+## Adding Tests for Bug Fixes
+
+When fixing a bug:
+
+1. **Write the failing test first** — reproduce the bug in a test
+2. **Verify it fails** — confirm the test catches the actual bug
+3. **Fix the bug** — make the test pass
+4. **Keep the test** — it prevents regression
+
+```typescript
+// Example: Bug #123 — formatCurrency returns NaN for undefined
+it('handles undefined input without NaN (bug #123)', () => {
+  expect(formatCurrency(undefined as unknown as number)).toBe('$0.00');
+});
+```
+
+## Coverage Report
+
+After running the coverage command:
+
+- Check terminal output for summary of all metrics
+- Check the coverage report directory (often `coverage/` or `htmlcov/`) for detailed line-by-line coverage
+- Uncovered lines are usually highlighted in the terminal or HTML report
+
+If coverage drops below the threshold on any metric, the test run **fails**. Add tests to cover the gap before committing.
+
+## Stack-Specific Guidance
+
+### Async/Event-Loop Systems
+
+For systems with async I/O or event loops (Node.js, Python asyncio, Go goroutines):
+- Mock all I/O operations (database, HTTP, file system)
+- Use the test framework's async support (`async/await` in tests)
+- Never use blocking I/O in tests for async systems — mock it or use async equivalents
+
+### Multi-Tenant/Authorization Systems
+
+For systems with tenant isolation or fine-grained authorization:
+- Every test for a scoped query/operation must verify scoping is correct
+- Test cross-tenant access attempts (should fail with 404 or 403)
+- Test missing authorization (should fail with 401 or 403)
+
+### API/HTTP Testing
+
+For REST/GraphQL/RPC APIs:
+- Test all response status codes (200, 201, 400, 401, 403, 404, 409, 422, 429, 500)
+- Test request validation (missing fields, wrong types, out-of-range values)
+- Test authentication and authorization
+- Test rate limiting if applicable
+
+### Frontend/UI Testing
+
+For component-based UI frameworks:
+- Test all UI states: loading, empty, error, success
+- Test user interactions with proper event simulation
+- Test accessibility (ARIA attributes, keyboard navigation, screen reader support)
+- Test responsive behavior if applicable (different viewport sizes)
+
+See `.claude/rules/responsive-and-accessibility.md` for UI-specific accessibility requirements.
+
+## Integration with Workflow
+
+This file defines unit testing standards. Integration and end-to-end testing are covered separately:
+- Unit tests run in the development pipeline (lint → type-check → unit tests → build)
+- Integration/E2E tests run in the testing phase of the SDLC pipeline (see `.claude/rules/mandatory-workflow.md`)
+- Coverage requirements apply to unit tests; integration tests have separate success criteria

claude_kit/_payload/rules/tool-design.md

@@ -0,0 +1,66 @@
+# Tool Design (tools & MCP for agents)
+
+When you build a tool, MCP server, script, or slash command for an agent to use, design it for an
+**agent consumer**, not a human one. The agent pays tokens for every tool definition it carries and
+every byte a tool prints, can't see a GUI, and reasons purely from text. A well-designed tool is as
+high-leverage as a well-written prompt — and a badly-designed one quietly burns the context budget and
+derails the agent.
+
+> Source: Mario Zechner, "What if you don't need MCP at all?"; Anthropic Engineering, "Building a C
+> compiler with a team of parallel Claudes"; "The Anatomy of an Agent Harness." Paraphrased for this kit.
+
+## 1. Prefer small composable tools over heavyweight always-loaded servers
+
+Every persistently-registered MCP server front-loads its whole tool schema into context **every turn**
+(often thousands of tokens) whether or not it's used. A small CLI/script the agent calls on demand
+costs ~nothing until invoked, and composes — its output can pipe into the next command. Reach for a
+persistent MCP server when you genuinely need stateful sessions, pushed events, or auth the agent
+can't hold; otherwise prefer a script the agent runs.
+
+## 2. Progressive disclosure
+
+Don't dump every capability up front. Expose a **name + one-line description**; load full usage only
+when the tool is actually used (the model behind `.claude/skills/`). This keeps the attention budget on
+the task — see `.claude/skills/context-engineering`.
+
+## 3. Name and scope for the model
+
+- **Action-oriented names** that say what the tool does.
+- **One clear job per tool** (tight granularity) — a few well-named tools beat many overlapping ones.
+- **Self-describing inputs/outputs** in the description, so the agent doesn't guess the contract.
+
+## 4. Design output for a context window
+
+- **Print sparsely.** A few lines of signal inline; write full detail to a file the agent can open if
+  it needs to. Dumping a 500-line log into context is how agents lose the thread.
+- **Single grep-friendly errors.** Emit failures as one line (`ERROR <reason>`) the agent can scan for.
+- **Pre-compute summaries** so the agent reasons from a compact signal, not raw output.
+- **Offer a fast/sampled mode** for tight iteration loops where full output isn't needed.
+
+## 5. Structured output for machine consumption
+
+When a result is consumed by code or another agent (not read by a human), return a **typed/validated
+structure**, not prose to be re-parsed. Schema-validated output removes a whole class of brittle
+string-parsing failures and makes fan-out/verification flows reliable
+(`.claude/skills/_references/orchestration-patterns.md`).
+
+## 6. Safe and idempotent
+
+A tool is a **privilege boundary** (`.claude/rules/agent-guardrails.md`): grant least privilege,
+validate inputs, make repeated calls safe to retry (idempotent), and gate destructive or
+outward-facing actions behind `.claude/rules/human-in-the-loop.md`.
+
+## Rules
+
+1. **Design for the agent, not a human dashboard** — text-first, token-aware, self-describing.
+2. **Composable-over-heavy** — a script the agent runs beats an always-loaded server unless you need
+   state/events/auth.
+3. **Sparse output + single-line errors + structured results** are the default, not a nicety.
+4. **Eval your tools too** — a tool's effect on agent success is measurable; see `.claude/rules/evals.md`.
+
+## Relationship to other rules
+
+- **`.claude/rules/agent-guardrails.md`** — tools as privilege boundary; least privilege; gating.
+- **`.claude/rules/reasoning-techniques.md`** / **`model-tiers.md`** — tool use is part of how an agent reasons.
+- **`.claude/rules/evals.md`** — measure whether a tool change actually helps.
+- **`catalog/mcp.yaml`** (kit authors) — where MCP servers are declared and wired into a project.

claude_kit/_payload/skills/_references/accessibility-checklist.md

@@ -0,0 +1,160 @@
+# Accessibility Checklist
+
+Quick reference for WCAG 2.1 AA compliance. Use alongside the `frontend-ui-engineering` skill.
+
+## Table of Contents
+
+- [Essential Checks](#essential-checks)
+- [Common HTML Patterns](#common-html-patterns)
+- [Testing Tools](#testing-tools)
+- [Quick Reference: ARIA Live Regions](#quick-reference-aria-live-regions)
+- [Common Anti-Patterns](#common-anti-patterns)
+
+## Essential Checks
+
+### Keyboard Navigation
+- [ ] All interactive elements focusable via Tab key
+- [ ] Focus order follows visual/logical order
+- [ ] Focus is visible (outline/ring on focused elements)
+- [ ] Custom widgets have keyboard support (Enter to activate, Escape to close)
+- [ ] No keyboard traps (user can always Tab away from a component)
+- [ ] Skip-to-content link at top of page - visible (at least) on keyboard focus
+- [ ] Modals trap focus while open, return focus on close
+
+### Screen Readers
+- [ ] All images have `alt` text (or `alt=""` for decorative images)
+- [ ] All form inputs have associated labels (`<label>` or `aria-label`)
+- [ ] Buttons and links have descriptive text (not "Click here")
+- [ ] Icon-only buttons have `aria-label`
+- [ ] Page has one `<h1>` and headings don't skip levels
+- [ ] Dynamic content changes announced (`aria-live` regions)
+- [ ] Tables have `<th>` headers with scope
+
+### Visual
+- [ ] Text contrast ≥ 4.5:1 (normal text) or ≥ 3:1 (large text, 18px+)
+- [ ] UI components contrast ≥ 3:1 against background
+- [ ] Color is not the only way to convey information
+- [ ] Text resizable to 200% without breaking layout
+- [ ] No content that flashes more than 3 times per second
+
+### Forms
+- [ ] Every input has a visible label
+- [ ] Required fields indicated (not by color alone)
+- [ ] Error messages specific and associated with the field
+- [ ] Error state visible by more than color (icon, text, border)
+- [ ] Form submission errors summarized and focusable
+- [ ] Known fields use autocomplete (for example `type="email" autocomplete="email"`)
+
+### Content
+- [ ] Language declared (`<html lang="en">`)
+- [ ] Page has a descriptive `<title>`
+- [ ] Links distinguish from surrounding text (not by color alone)
+- [ ] Touch targets ≥ 44x44px on mobile
+- [ ] Meaningful empty states (not blank screens)
+
+## Common HTML Patterns
+
+### Buttons vs. Links
+
+```html
+<!-- Use <button> for actions -->
+<button onClick={handleDelete}>Delete Task</button>
+
+<!-- Use <a> for navigation -->
+<a href="/tasks/123">View Task</a>
+
+<!-- NEVER use div/span as buttons -->
+<div onClick={handleDelete}>Delete</div>  <!-- BAD -->
+```
+
+### Form Labels
+
+```html
+<!-- Explicit label association -->
+<label htmlFor="email">Email address</label>
+<input id="email" type="email" required />
+
+<!-- Implicit wrapping -->
+<label>
+  Email address
+  <input type="email" required />
+</label>
+
+<!-- Hidden label (visible label preferred) -->
+<input type="search" aria-label="Search tasks" />
+```
+
+### ARIA Roles
+
+```html
+<!-- Navigation -->
+<nav aria-label="Main navigation">...</nav>
+<nav aria-label="Footer links">...</nav>
+
+<!-- Status messages -->
+<div role="status" aria-live="polite">Task saved</div>
+
+<!-- Alert messages -->
+<div role="alert">Error: Title is required</div>
+
+<!-- Modal dialogs -->
+<dialog aria-modal="true" aria-labelledby="dialog-title">
+  <h2 id="dialog-title">Confirm Delete</h2>
+  ...
+</dialog>
+
+<!-- Loading states -->
+<div aria-busy="true" aria-label="Loading tasks">
+  <Spinner />
+</div>
+```
+
+### Accessible Lists
+
+```html
+<ul role="list" aria-label="Tasks">
+  <li>
+    <input type="checkbox" id="task-1" aria-label="Complete: Buy groceries" />
+    <label htmlFor="task-1">Buy groceries</label>
+  </li>
+</ul>
+```
+
+## Testing Tools
+
+```bash
+# Automated audit
+npx axe-core          # Programmatic accessibility testing
+npx pa11y             # CLI accessibility checker
+
+# In browser
+# Chrome DevTools → Lighthouse → Accessibility
+# Chrome DevTools → Elements → Accessibility tree
+
+# Screen reader testing
+# macOS: VoiceOver (Cmd + F5)
+# Windows: NVDA (free) or JAWS
+# Linux: Orca
+```
+
+## Quick Reference: ARIA Live Regions
+
+| Value | Behavior | Use For |
+|-------|----------|---------|
+| `aria-live="polite"` | Announced at next pause | Status updates, saved confirmations |
+| `aria-live="assertive"` | Announced immediately | Errors, time-sensitive alerts |
+| `role="status"` | Same as `polite` | Status messages |
+| `role="alert"` | Same as `assertive` | Error messages |
+
+## Common Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| `div` as button | Not focusable, no keyboard support | Use `<button>` |
+| Missing `alt` text | Images invisible to screen readers | Add descriptive `alt` |
+| Color-only states | Invisible to color-blind users | Add icons, text, or patterns |
+| Autoplaying media | Disorienting, can't be stopped | Add controls, don't autoplay |
+| Custom dropdown with no ARIA | Unusable by keyboard/screen reader | Use native `<select>` or proper ARIA listbox |
+| Removing focus outlines | Users can't see where they are | Style outlines, don't remove them |
+| Empty links/buttons | "Link" announced with no description | Add text or `aria-label` |
+| `tabindex > 0` | Breaks natural tab order | Use `tabindex="0"` or `-1` only |