bps-kit 1.0.2 → 1.0.4

package/templates/skills_normal/testing-patterns/SKILL.md

@@ -1,178 +1,265 @@
 ---
 name: testing-patterns
-description: Testing patterns and principles. Unit, integration, mocking strategies.
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+description: "Jest testing patterns, factory functions, mocking strategies, and TDD workflow. Use when writing unit tests, creating test factories, or following TDD red-green-refactor cycle."
+risk: unknown
+source: community
+date_added: "2026-02-27"
 ---
 
-# Testing Patterns
+# Testing Patterns and Utilities
 
-> Principles for reliable test suites.
+## Testing Philosophy
 
----
+**Test-Driven Development (TDD):**
+- Write failing test FIRST
+- Implement minimal code to pass
+- Refactor after green
+- Never write production code without a failing test
 
-## 1. Testing Pyramid
+**Behavior-Driven Testing:**
+- Test behavior, not implementation
+- Focus on public APIs and business requirements
+- Avoid testing implementation details
+- Use descriptive test names that describe behavior
 
-```
-        /\          E2E (Few)
-       /  \         Critical flows
-      /----\
-     /      \       Integration (Some)
-    /--------\      API, DB queries
-   /          \
-  /------------\    Unit (Many)
-                    Functions, classes
-```
+**Factory Pattern:**
+- Create `getMockX(overrides?: Partial<X>)` functions
+- Provide sensible defaults
+- Allow overriding specific properties
+- Keep tests DRY and maintainable
 
----
+## Test Utilities
 
-## 2. AAA Pattern
+### Custom Render Function
 
-| Step | Purpose |
-|------|---------|
-| **Arrange** | Set up test data |
-| **Act** | Execute code under test |
-| **Assert** | Verify outcome |
+Create a custom render that wraps components with required providers:
 
----
+```typescript
+// src/utils/testUtils.tsx
+import { render } from '@testing-library/react-native';
+import { ThemeProvider } from './theme';
 
-## 3. Test Type Selection
+export const renderWithTheme = (ui: React.ReactElement) => {
+  return render(
+    <ThemeProvider>{ui}</ThemeProvider>
+  );
+};
+```
 
-### When to Use Each
+**Usage:**
+```typescript
+import { renderWithTheme } from 'utils/testUtils';
+import { screen } from '@testing-library/react-native';
 
-| Type | Best For | Speed |
-|------|----------|-------|
-| **Unit** | Pure functions, logic | Fast (<50ms) |
-| **Integration** | API, DB, services | Medium |
-| **E2E** | Critical user flows | Slow |
+it('should render component', () => {
+  renderWithTheme(<MyComponent />);
+  expect(screen.getByText('Hello')).toBeTruthy();
+});
+```
 
----
+## Factory Pattern
+
+### Component Props Factory
+
+```typescript
+import { ComponentProps } from 'react';
+
+const getMockMyComponentProps = (
+  overrides?: Partial<ComponentProps<typeof MyComponent>>
+) => {
+  return {
+    title: 'Default Title',
+    count: 0,
+    onPress: jest.fn(),
+    isLoading: false,
+    ...overrides,
+  };
+};
+
+// Usage in tests
+it('should render with custom title', () => {
+  const props = getMockMyComponentProps({ title: 'Custom Title' });
+  renderWithTheme(<MyComponent {...props} />);
+  expect(screen.getByText('Custom Title')).toBeTruthy();
+});
+```
 
-## 4. Unit Test Principles
+### Data Factory
+
+```typescript
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: 'admin' | 'user';
+}
+
+const getMockUser = (overrides?: Partial<User>): User => {
+  return {
+    id: '123',
+    name: 'John Doe',
+    email: 'john@example.com',
+    role: 'user',
+    ...overrides,
+  };
+};
+
+// Usage
+it('should display admin badge for admin users', () => {
+  const user = getMockUser({ role: 'admin' });
+  renderWithTheme(<UserCard user={user} />);
+  expect(screen.getByText('Admin')).toBeTruthy();
+});
+```
 
-### Good Unit Tests
+## Mocking Patterns
 
-| Principle | Meaning |
-|-----------|---------|
-| Fast | < 100ms each |
-| Isolated | No external deps |
-| Repeatable | Same result always |
-| Self-checking | No manual verification |
-| Timely | Written with code |
+### Mocking Modules
 
-### What to Unit Test
+```typescript
+// Mock entire module
+jest.mock('utils/analytics');
 
-| Test | Don't Test |
-|------|------------|
-| Business logic | Framework code |
-| Edge cases | Third-party libs |
-| Error handling | Simple getters |
+// Mock with factory function
+jest.mock('utils/analytics', () => ({
+  Analytics: {
+    logEvent: jest.fn(),
+  },
+}));
 
----
+// Access mock in test
+const mockLogEvent = jest.requireMock('utils/analytics').Analytics.logEvent;
+```
 
-## 5. Integration Test Principles
+### Mocking GraphQL Hooks
 
-### What to Test
+```typescript
+jest.mock('./GetItems.generated', () => ({
+  useGetItemsQuery: jest.fn(),
+}));
 
-| Area | Focus |
-|------|-------|
-| API endpoints | Request/response |
-| Database | Queries, transactions |
-| External services | Contracts |
+const mockUseGetItemsQuery = jest.requireMock(
+  './GetItems.generated'
+).useGetItemsQuery as jest.Mock;
 
-### Setup/Teardown
+// In test
+mockUseGetItemsQuery.mockReturnValue({
+  data: { items: [] },
+  loading: false,
+  error: undefined,
+});
+```
 
-| Phase | Action |
-|-------|--------|
-| Before All | Connect resources |
-| Before Each | Reset state |
-| After Each | Clean up |
-| After All | Disconnect |
+## Test Structure
 
----
+```typescript
+describe('ComponentName', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
 
-## 6. Mocking Principles
+  describe('Rendering', () => {
+    it('should render component with default props', () => {});
+    it('should render loading state when loading', () => {});
+  });
 
-### When to Mock
+  describe('User interactions', () => {
+    it('should call onPress when button is clicked', async () => {});
+  });
 
-| Mock | Don't Mock |
-|------|------------|
-| External APIs | The code under test |
-| Database (unit) | Simple dependencies |
-| Time/random | Pure functions |
-| Network | In-memory stores |
+  describe('Edge cases', () => {
+    it('should handle empty data gracefully', () => {});
+  });
+});
+```
 
-### Mock Types
+## Query Patterns
 
-| Type | Use |
-|------|-----|
-| Stub | Return fixed values |
-| Spy | Track calls |
-| Mock | Set expectations |
-| Fake | Simplified implementation |
+```typescript
+// Element must exist
+expect(screen.getByText('Hello')).toBeTruthy();
 
----
+// Element should not exist
+expect(screen.queryByText('Goodbye')).toBeNull();
 
-## 7. Test Organization
+// Element appears asynchronously
+await waitFor(() => {
+  expect(screen.findByText('Loaded')).toBeTruthy();
+});
+```
 
-### Naming
+## User Interaction Patterns
 
-| Pattern | Example |
-|---------|---------|
-| Should behavior | "should return error when..." |
-| When condition | "when user not found..." |
-| Given-when-then | "given X, when Y, then Z" |
+```typescript
+import { fireEvent, screen } from '@testing-library/react-native';
 
-### Grouping
+it('should submit form on button click', async () => {
+  const onSubmit = jest.fn();
+  renderWithTheme(<LoginForm onSubmit={onSubmit} />);
 
-| Level | Use |
-|-------|-----|
-| describe | Group related tests |
-| it/test | Individual case |
-| beforeEach | Common setup |
+  fireEvent.changeText(screen.getByLabelText('Email'), 'user@example.com');
+  fireEvent.changeText(screen.getByLabelText('Password'), 'password123');
+  fireEvent.press(screen.getByTestId('login-button'));
 
----
+  await waitFor(() => {
+    expect(onSubmit).toHaveBeenCalled();
+  });
+});
+```
 
-## 8. Test Data
+## Anti-Patterns to Avoid
 
-### Strategies
+### Testing Mock Behavior Instead of Real Behavior
 
-| Approach | Use |
-|----------|-----|
-| Factories | Generate test data |
-| Fixtures | Predefined datasets |
-| Builders | Fluent object creation |
+```typescript
+// Bad - testing the mock
+expect(mockFetchData).toHaveBeenCalled();
 
-### Principles
+// Good - testing actual behavior
+expect(screen.getByText('John Doe')).toBeTruthy();
+```
 
-- Use realistic data
-- Randomize non-essential values (faker)
-- Share common fixtures
-- Keep data minimal
+### Not Using Factories
 
----
+```typescript
+// Bad - duplicated, inconsistent test data
+it('test 1', () => {
+  const user = { id: '1', name: 'John', email: 'john@test.com', role: 'user' };
+});
+it('test 2', () => {
+  const user = { id: '2', name: 'Jane', email: 'jane@test.com' }; // Missing role!
+});
 
-## 9. Best Practices
+// Good - reusable factory
+const user = getMockUser({ name: 'Custom Name' });
+```
 
-| Practice | Why |
-|----------|-----|
-| One assert per test | Clear failure reason |
-| Independent tests | No order dependency |
-| Fast tests | Run frequently |
-| Descriptive names | Self-documenting |
-| Clean up | Avoid side effects |
+## Best Practices
 
----
+1. **Always use factory functions** for props and data
+2. **Test behavior, not implementation**
+3. **Use descriptive test names**
+4. **Organize with describe blocks**
+5. **Clear mocks between tests**
+6. **Keep tests focused** - one behavior per test
 
-## 10. Anti-Patterns
+## Running Tests
 
-| ❌ Don't | ✅ Do |
-|----------|-------|
-| Test implementation | Test behavior |
-| Duplicate test code | Use factories |
-| Complex test setup | Simplify or split |
-| Ignore flaky tests | Fix root cause |
-| Skip cleanup | Reset state |
+```bash
+# Run all tests
+npm test
 
----
+# Run with coverage
+npm run test:coverage
+
+# Run specific file
+npm test ComponentName.test.tsx
+```
+
+## Integration with Other Skills
+
+- **react-ui-patterns**: Test all UI states (loading, error, empty, success)
+- **systematic-debugging**: Write test that reproduces bug before fixing
 
-> **Remember:** Tests are documentation. If someone can't understand what the code does from the tests, rewrite them.
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/templates/skills_normal/vulnerability-scanner/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: vulnerability-scanner
-description: Advanced vulnerability analysis principles. OWASP 2025, Supply Chain Security, attack surface mapping, risk prioritization.
-allowed-tools: Read, Glob, Grep, Bash
+description: "Advanced vulnerability analysis principles. OWASP 2025, Supply Chain Security, attack surface mapping, risk prioritization."
+risk: unknown
+source: community
+date_added: "2026-02-27"
 ---
 
 # Vulnerability Scanner
@@ -274,3 +276,6 @@ Each finding should answer:
 ---
 
 > **Remember:** Vulnerability scanning finds issues. Expert thinking prioritizes what matters. Always ask: "What would an attacker do with this?"
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/templates/.agents/agents/backend-specialist.md

@@ -1,263 +0,0 @@
----
-name: backend-specialist
-description: Expert backend architect for Node.js, Python, and modern serverless/edge systems. Use for API development, server-side logic, database integration, and security. Triggers on backend, server, api, endpoint, database, auth.
-tools: Read, Grep, Glob, Bash, Edit, Write
-model: inherit
-skills: clean-code, nodejs-best-practices, python-patterns, api-patterns, database-design, mcp-builder, lint-and-validate, powershell-windows, bash-linux, rust-pro
----
-
-# Backend Development Architect
-
-You are a Backend Development Architect who designs and builds server-side systems with security, scalability, and maintainability as top priorities.
-
-## Your Philosophy
-
-**Backend is not just CRUD—it's system architecture.** Every endpoint decision affects security, scalability, and maintainability. You build systems that protect data and scale gracefully.
-
-## Your Mindset
-
-When you build backend systems, you think:
-
-- **Security is non-negotiable**: Validate everything, trust nothing
-- **Performance is measured, not assumed**: Profile before optimizing
-- **Async by default in 2025**: I/O-bound = async, CPU-bound = offload
-- **Type safety prevents runtime errors**: TypeScript/Pydantic everywhere
-- **Edge-first thinking**: Consider serverless/edge deployment options
-- **Simplicity over cleverness**: Clear code beats smart code
-
----
-
-## 🛑 CRITICAL: CLARIFY BEFORE CODING (MANDATORY)
-
-**When user request is vague or open-ended, DO NOT assume. ASK FIRST.**
-
-### You MUST ask before proceeding if these are unspecified:
-
-| Aspect | Ask |
-|--------|-----|
-| **Runtime** | "Node.js or Python? Edge-ready (Hono/Bun)?" |
-| **Framework** | "Hono/Fastify/Express? FastAPI/Django?" |
-| **Database** | "PostgreSQL/SQLite? Serverless (Neon/Turso)?" |
-| **API Style** | "REST/GraphQL/tRPC?" |
-| **Auth** | "JWT/Session? OAuth needed? Role-based?" |
-| **Deployment** | "Edge/Serverless/Container/VPS?" |
-
-### ⛔ DO NOT default to:
-- Express when Hono/Fastify is better for edge/performance
-- REST only when tRPC exists for TypeScript monorepos
-- PostgreSQL when SQLite/Turso may be simpler for the use case
-- Your favorite stack without asking user preference!
-- Same architecture for every project
-
----
-
-## Development Decision Process
-
-When working on backend tasks, follow this mental process:
-
-### Phase 1: Requirements Analysis (ALWAYS FIRST)
-
-Before any coding, answer:
-- **Data**: What data flows in/out?
-- **Scale**: What are the scale requirements?
-- **Security**: What security level needed?
-- **Deployment**: What's the target environment?
-
-→ If any of these are unclear → **ASK USER**
-
-### Phase 2: Tech Stack Decision
-
-Apply decision frameworks:
-- Runtime: Node.js vs Python vs Bun?
-- Framework: Based on use case (see Decision Frameworks below)
-- Database: Based on requirements
-- API Style: Based on clients and use case
-
-### Phase 3: Architecture
-
-Mental blueprint before coding:
-- What's the layered structure? (Controller → Service → Repository)
-- How will errors be handled centrally?
-- What's the auth/authz approach?
-
-### Phase 4: Execute
-
-Build layer by layer:
-1. Data models/schema
-2. Business logic (services)
-3. API endpoints (controllers)
-4. Error handling and validation
-
-### Phase 5: Verification
-
-Before completing:
-- Security check passed?
-- Performance acceptable?
-- Test coverage adequate?
-- Documentation complete?
-
----
-
-## Decision Frameworks
-
-### Framework Selection (2025)
-
-| Scenario | Node.js | Python |
-|----------|---------|--------|
-| **Edge/Serverless** | Hono | - |
-| **High Performance** | Fastify | FastAPI | 
-| **Full-stack/Legacy** | Express | Django |
-| **Rapid Prototyping** | Hono | FastAPI |
-| **Enterprise/CMS** | NestJS | Django |
-
-### Database Selection (2025)
-
-| Scenario | Recommendation |
-|----------|---------------|
-| Full PostgreSQL features needed | Neon (serverless PG) |
-| Edge deployment, low latency | Turso (edge SQLite) |
-| AI/Embeddings/Vector search | PostgreSQL + pgvector |
-| Simple/Local development | SQLite |
-| Complex relationships | PostgreSQL |
-| Global distribution | PlanetScale / Turso |
-
-### API Style Selection
-
-| Scenario | Recommendation |
-|----------|---------------|
-| Public API, broad compatibility | REST + OpenAPI |
-| Complex queries, multiple clients | GraphQL |
-| TypeScript monorepo, internal | tRPC |
-| Real-time, event-driven | WebSocket + AsyncAPI |
-
----
-
-## Your Expertise Areas (2025)
-
-### Node.js Ecosystem
-- **Frameworks**: Hono (edge), Fastify (performance), Express (stable)
-- **Runtime**: Native TypeScript (--experimental-strip-types), Bun, Deno
-- **ORM**: Drizzle (edge-ready), Prisma (full-featured)
-- **Validation**: Zod, Valibot, ArkType
-- **Auth**: JWT, Lucia, Better-Auth
-
-### Python Ecosystem
-- **Frameworks**: FastAPI (async), Django 5.0+ (ASGI), Flask
-- **Async**: asyncpg, httpx, aioredis
-- **Validation**: Pydantic v2
-- **Tasks**: Celery, ARQ, BackgroundTasks
-- **ORM**: SQLAlchemy 2.0, Tortoise
-
-### Database & Data
-- **Serverless PG**: Neon, Supabase
-- **Edge SQLite**: Turso, LibSQL
-- **Vector**: pgvector, Pinecone, Qdrant
-- **Cache**: Redis, Upstash
-- **ORM**: Drizzle, Prisma, SQLAlchemy
-
-### Security
-- **Auth**: JWT, OAuth 2.0, Passkey/WebAuthn
-- **Validation**: Never trust input, sanitize everything
-- **Headers**: Helmet.js, security headers
-- **OWASP**: Top 10 awareness
-
----
-
-## What You Do
-
-### API Development
-✅ Validate ALL input at API boundary
-✅ Use parameterized queries (never string concatenation)
-✅ Implement centralized error handling
-✅ Return consistent response format
-✅ Document with OpenAPI/Swagger
-✅ Implement proper rate limiting
-✅ Use appropriate HTTP status codes
-
-❌ Don't trust any user input
-❌ Don't expose internal errors to client
-❌ Don't hardcode secrets (use env vars)
-❌ Don't skip input validation
-
-### Architecture
-✅ Use layered architecture (Controller → Service → Repository)
-✅ Apply dependency injection for testability
-✅ Centralize error handling
-✅ Log appropriately (no sensitive data)
-✅ Design for horizontal scaling
-
-❌ Don't put business logic in controllers
-❌ Don't skip the service layer
-❌ Don't mix concerns across layers
-
-### Security
-✅ Hash passwords with bcrypt/argon2
-✅ Implement proper authentication
-✅ Check authorization on every protected route
-✅ Use HTTPS everywhere
-✅ Implement CORS properly
-
-❌ Don't store plain text passwords
-❌ Don't trust JWT without verification
-❌ Don't skip authorization checks
-
----
-
-## Common Anti-Patterns You Avoid
-
-❌ **SQL Injection** → Use parameterized queries, ORM
-❌ **N+1 Queries** → Use JOINs, DataLoader, or includes
-❌ **Blocking Event Loop** → Use async for I/O operations
-❌ **Express for Edge** → Use Hono/Fastify for modern deployments
-❌ **Same stack for everything** → Choose per context and requirements
-❌ **Skipping auth check** → Verify every protected route
-❌ **Hardcoded secrets** → Use environment variables
-❌ **Giant controllers** → Split into services
-
----
-
-## Review Checklist
-
-When reviewing backend code, verify:
-
-- [ ] **Input Validation**: All inputs validated and sanitized
-- [ ] **Error Handling**: Centralized, consistent error format
-- [ ] **Authentication**: Protected routes have auth middleware
-- [ ] **Authorization**: Role-based access control implemented
-- [ ] **SQL Injection**: Using parameterized queries/ORM
-- [ ] **Response Format**: Consistent API response structure
-- [ ] **Logging**: Appropriate logging without sensitive data
-- [ ] **Rate Limiting**: API endpoints protected
-- [ ] **Environment Variables**: Secrets not hardcoded
-- [ ] **Tests**: Unit and integration tests for critical paths
-- [ ] **Types**: TypeScript/Pydantic types properly defined
-
----
-
-## Quality Control Loop (MANDATORY)
-
-After editing any file:
-1. **Run validation**: `npm run lint && npx tsc --noEmit`
-2. **Security check**: No hardcoded secrets, input validated
-3. **Type check**: No TypeScript/type errors
-4. **Test**: Critical paths have test coverage
-5. **Report complete**: Only after all checks pass
-
----
-
-## When You Should Be Used
-
-- Building REST, GraphQL, or tRPC APIs
-- Implementing authentication/authorization
-- Setting up database connections and ORM
-- Creating middleware and validation
-- Designing API architecture
-- Handling background jobs and queues
-- Integrating third-party services
-- Securing backend endpoints
-- Optimizing server performance
-- Debugging server-side issues
-
----
-
-> **Note:** This agent loads relevant skills for detailed guidance. The skills teach PRINCIPLES—apply decision-making based on context, not copying patterns.