@ngxtm/devkit 3.6.1 → 3.8.0

package/merged-commands/core-components.md

@@ -0,0 +1,264 @@
+---
+name: core-components
+description: Core component library and design system patterns. Use when building UI, using design tokens, or working with the component library.
+---
+
+# Core Components
+
+## Design System Overview
+
+Use components from your core library instead of raw platform components. This ensures consistent styling and behavior.
+
+## Design Tokens
+
+**NEVER hard-code values. Always use design tokens.**
+
+### Spacing Tokens
+
+```tsx
+// CORRECT - Use tokens
+<Box padding="$4" marginBottom="$2" />
+
+// WRONG - Hard-coded values
+<Box padding={16} marginBottom={8} />
+```
+
+| Token | Value |
+|-------|-------|
+| `$1` | 4px |
+| `$2` | 8px |
+| `$3` | 12px |
+| `$4` | 16px |
+| `$6` | 24px |
+| `$8` | 32px |
+
+### Color Tokens
+
+```tsx
+// CORRECT - Semantic tokens
+<Text color="$textPrimary" />
+<Box backgroundColor="$backgroundSecondary" />
+
+// WRONG - Hard-coded colors
+<Text color="#333333" />
+<Box backgroundColor="rgb(245, 245, 245)" />
+```
+
+| Semantic Token | Use For |
+|----------------|---------|
+| `$textPrimary` | Main text |
+| `$textSecondary` | Supporting text |
+| `$textTertiary` | Disabled/hint text |
+| `$primary500` | Brand/accent color |
+| `$statusError` | Error states |
+| `$statusSuccess` | Success states |
+
+### Typography Tokens
+
+```tsx
+<Text fontSize="$lg" fontWeight="$semibold" />
+```
+
+| Token | Size |
+|-------|------|
+| `$xs` | 12px |
+| `$sm` | 14px |
+| `$md` | 16px |
+| `$lg` | 18px |
+| `$xl` | 20px |
+| `$2xl` | 24px |
+
+## Core Components
+
+### Box
+
+Base layout component with token support:
+
+```tsx
+<Box
+  padding="$4"
+  backgroundColor="$backgroundPrimary"
+  borderRadius="$lg"
+>
+  {children}
+</Box>
+```
+
+### HStack / VStack
+
+Horizontal and vertical flex layouts:
+
+```tsx
+<HStack gap="$3" alignItems="center">
+  <Icon name="user" />
+  <Text>Username</Text>
+</HStack>
+
+<VStack gap="$4" padding="$4">
+  <Heading>Title</Heading>
+  <Text>Content</Text>
+</VStack>
+```
+
+### Text
+
+Typography with token support:
+
+```tsx
+<Text
+  fontSize="$lg"
+  fontWeight="$semibold"
+  color="$textPrimary"
+>
+  Hello World
+</Text>
+```
+
+### Button
+
+Interactive button with variants:
+
+```tsx
+<Button
+  onPress={handlePress}
+  variant="solid"
+  size="md"
+  isLoading={loading}
+  isDisabled={disabled}
+>
+  Click Me
+</Button>
+```
+
+| Variant | Use For |
+|---------|---------|
+| `solid` | Primary actions |
+| `outline` | Secondary actions |
+| `ghost` | Tertiary/subtle actions |
+| `link` | Inline actions |
+
+### Input
+
+Form input with validation:
+
+```tsx
+<Input
+  value={value}
+  onChangeText={setValue}
+  placeholder="Enter text"
+  error={touched ? errors.field : undefined}
+  label="Field Name"
+/>
+```
+
+### Card
+
+Content container:
+
+```tsx
+<Card padding="$4" gap="$3">
+  <CardHeader>
+    <Heading size="sm">Card Title</Heading>
+  </CardHeader>
+  <CardBody>
+    <Text>Card content</Text>
+  </CardBody>
+</Card>
+```
+
+## Layout Patterns
+
+### Screen Layout
+
+```tsx
+const MyScreen = () => (
+  <Screen>
+    <ScreenHeader title="Page Title" />
+    <ScreenContent padding="$4">
+      {/* Content */}
+    </ScreenContent>
+  </Screen>
+);
+```
+
+### Form Layout
+
+```tsx
+<VStack gap="$4" padding="$4">
+  <Input label="Name" {...nameProps} />
+  <Input label="Email" {...emailProps} />
+  <Button isLoading={loading}>Submit</Button>
+</VStack>
+```
+
+### List Item Layout
+
+```tsx
+<HStack
+  padding="$4"
+  gap="$3"
+  alignItems="center"
+  borderBottomWidth={1}
+  borderColor="$borderLight"
+>
+  <Avatar source={{ uri: imageUrl }} size="md" />
+  <VStack flex={1}>
+    <Text fontWeight="$semibold">{title}</Text>
+    <Text color="$textSecondary" fontSize="$sm">{subtitle}</Text>
+  </VStack>
+  <Icon name="chevron-right" color="$textTertiary" />
+</HStack>
+```
+
+## Anti-Patterns
+
+```tsx
+// WRONG - Hard-coded values
+<View style={{ padding: 16, backgroundColor: '#fff' }}>
+
+// CORRECT - Design tokens
+<Box padding="$4" backgroundColor="$backgroundPrimary">
+
+
+// WRONG - Raw platform components
+import { View, Text } from 'react-native';
+
+// CORRECT - Core components
+import { Box, Text } from 'components/core';
+
+
+// WRONG - Inline styles
+<Text style={{ fontSize: 18, fontWeight: '600' }}>
+
+// CORRECT - Token props
+<Text fontSize="$lg" fontWeight="$semibold">
+```
+
+## Component Props Pattern
+
+When creating components, use token-based props:
+
+```tsx
+interface CardProps {
+  padding?: '$2' | '$4' | '$6';
+  variant?: 'elevated' | 'outlined' | 'filled';
+  children: React.ReactNode;
+}
+
+const Card = ({ padding = '$4', variant = 'elevated', children }: CardProps) => (
+  <Box
+    padding={padding}
+    backgroundColor="$backgroundPrimary"
+    borderRadius="$lg"
+    {...variantStyles[variant]}
+  >
+    {children}
+  </Box>
+);
+```
+
+## Integration with Other Skills
+
+- **react-ui-patterns**: Use core components for UI states
+- **testing-patterns**: Mock core components in tests
+- **storybook**: Document component variants

package/merged-commands/cosmos-db-python-skill.md

@@ -0,0 +1,198 @@
+---
+name: cosmos-db-python-skill
+description: Build Azure Cosmos DB NoSQL services with Python/FastAPI following production-grade patterns. Use when implementing database client setup with dual auth (DefaultAzureCredential + emulator), service layer classes with CRUD operations, partition key strategies, parameterized queries, or TDD patterns for Cosmos. Triggers on phrases like "Cosmos DB", "NoSQL database", "document store", "add persistence", "database service layer", or "Python Cosmos SDK".
+---
+
+# Cosmos DB Service Implementation
+
+Build production-grade Azure Cosmos DB NoSQL services following clean code, security best practices, and TDD principles.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         FastAPI Router                          │
+│  - Auth dependencies (get_current_user, get_current_user_required)
+│  - HTTP error responses (HTTPException)                         │
+└──────────────────────────────┬──────────────────────────────────┘
+                               │
+┌──────────────────────────────▼──────────────────────────────────┐
+│                        Service Layer                            │
+│  - Business logic and validation                                │
+│  - Document ↔ Model conversion                                  │
+│  - Graceful degradation when Cosmos unavailable                 │
+└──────────────────────────────┬──────────────────────────────────┘
+                               │
+┌──────────────────────────────▼──────────────────────────────────┐
+│                     Cosmos DB Client Module                     │
+│  - Singleton container initialization                           │
+│  - Dual auth: DefaultAzureCredential (Azure) / Key (emulator)   │
+│  - Async wrapper via run_in_threadpool                          │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Quick Start
+
+### 1. Client Module Setup
+
+Create a singleton Cosmos client with dual authentication:
+
+```python
+# db/cosmos.py
+from azure.cosmos import CosmosClient
+from azure.identity import DefaultAzureCredential
+from starlette.concurrency import run_in_threadpool
+
+_cosmos_container = None
+
+def _is_emulator_endpoint(endpoint: str) -> bool:
+    return "localhost" in endpoint or "127.0.0.1" in endpoint
+
+async def get_container():
+    global _cosmos_container
+    if _cosmos_container is None:
+        if _is_emulator_endpoint(settings.cosmos_endpoint):
+            client = CosmosClient(
+                url=settings.cosmos_endpoint,
+                credential=settings.cosmos_key,
+                connection_verify=False
+            )
+        else:
+            client = CosmosClient(
+                url=settings.cosmos_endpoint,
+                credential=DefaultAzureCredential()
+            )
+        db = client.get_database_client(settings.cosmos_database_name)
+        _cosmos_container = db.get_container_client(settings.cosmos_container_id)
+    return _cosmos_container
+```
+
+**Full implementation**: See [references/client-setup.md](references/client-setup.md)
+
+### 2. Pydantic Model Hierarchy
+
+Use five-tier model pattern for clean separation:
+
+```python
+class ProjectBase(BaseModel):           # Shared fields
+    name: str = Field(..., min_length=1, max_length=200)
+
+class ProjectCreate(ProjectBase):       # Creation request
+    workspace_id: str = Field(..., alias="workspaceId")
+
+class ProjectUpdate(BaseModel):         # Partial updates (all optional)
+    name: Optional[str] = Field(None, min_length=1)
+
+class Project(ProjectBase):             # API response
+    id: str
+    created_at: datetime = Field(..., alias="createdAt")
+
+class ProjectInDB(Project):             # Internal with docType
+    doc_type: str = "project"
+```
+
+### 3. Service Layer Pattern
+
+```python
+class ProjectService:
+    def _use_cosmos(self) -> bool:
+        return get_container() is not None
+    
+    async def get_by_id(self, project_id: str, workspace_id: str) -> Project | None:
+        if not self._use_cosmos():
+            return None
+        doc = await get_document(project_id, partition_key=workspace_id)
+        if doc is None:
+            return None
+        return self._doc_to_model(doc)
+```
+
+**Full patterns**: See [references/service-layer.md](references/service-layer.md)
+
+## Core Principles
+
+### Security Requirements
+
+1. **RBAC Authentication**: Use `DefaultAzureCredential` in Azure — never store keys in code
+2. **Emulator-Only Keys**: Hardcode the well-known emulator key only for local development
+3. **Parameterized Queries**: Always use `@parameter` syntax — never string concatenation
+4. **Partition Key Validation**: Validate partition key access matches user authorization
+
+### Clean Code Conventions
+
+1. **Single Responsibility**: Client module handles connection; services handle business logic
+2. **Graceful Degradation**: Services return `None`/`[]` when Cosmos unavailable
+3. **Consistent Naming**: `_doc_to_model()`, `_model_to_doc()`, `_use_cosmos()`
+4. **Type Hints**: Full typing on all public methods
+5. **CamelCase Aliases**: Use `Field(alias="camelCase")` for JSON serialization
+
+### TDD Requirements
+
+Write tests BEFORE implementation using these patterns:
+
+```python
+@pytest.fixture
+def mock_cosmos_container(mocker):
+    container = mocker.MagicMock()
+    mocker.patch("app.db.cosmos.get_container", return_value=container)
+    return container
+
+@pytest.mark.asyncio
+async def test_get_project_by_id_returns_project(mock_cosmos_container):
+    # Arrange
+    mock_cosmos_container.read_item.return_value = {"id": "123", "name": "Test"}
+    
+    # Act
+    result = await project_service.get_by_id("123", "workspace-1")
+    
+    # Assert
+    assert result.id == "123"
+    assert result.name == "Test"
+```
+
+**Full testing guide**: See [references/testing.md](references/testing.md)
+
+## Reference Files
+
+| File | When to Read |
+|------|--------------|
+| [references/client-setup.md](references/client-setup.md) | Setting up Cosmos client with dual auth, SSL config, singleton pattern |
+| [references/service-layer.md](references/service-layer.md) | Implementing full service class with CRUD, conversions, graceful degradation |
+| [references/testing.md](references/testing.md) | Writing pytest tests, mocking Cosmos, integration test setup |
+| [references/partitioning.md](references/partitioning.md) | Choosing partition keys, cross-partition queries, move operations |
+| [references/error-handling.md](references/error-handling.md) | Handling CosmosResourceNotFoundError, logging, HTTP error mapping |
+
+## Template Files
+
+| File | Purpose |
+|------|---------|
+| [assets/cosmos_client_template.py](assets/cosmos_client_template.py) | Ready-to-use client module |
+| [assets/service_template.py](assets/service_template.py) | Service class skeleton |
+| [assets/conftest_template.py](assets/conftest_template.py) | pytest fixtures for Cosmos mocking |
+
+## Quality Attributes (NFRs)
+
+### Reliability
+- Graceful degradation when Cosmos unavailable
+- Retry logic with exponential backoff for transient failures
+- Connection pooling via singleton pattern
+
+### Security
+- Zero secrets in code (RBAC via DefaultAzureCredential)
+- Parameterized queries prevent injection
+- Partition key isolation enforces data boundaries
+
+### Maintainability
+- Five-tier model pattern enables schema evolution
+- Service layer decouples business logic from storage
+- Consistent patterns across all entity services
+
+### Testability
+- Dependency injection via `get_container()`
+- Easy mocking with module-level globals
+- Clear separation enables unit testing without Cosmos
+
+### Performance
+- Partition key queries avoid cross-partition scans
+- Async wrapping prevents blocking FastAPI event loop
+- Minimal document conversion overhead