codeforge-dev 1.7.0 → 1.9.0

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/documentation-patterns/references/api-doc-templates.md

@@ -0,0 +1,221 @@
+# API Documentation Templates
+
+## REST Endpoint Documentation
+
+Use this template for each API endpoint:
+
+### Template
+
+```markdown
+## [Method] [Path]
+
+[One-sentence description of what this endpoint does.]
+
+### Request
+
+**URL Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | string | Yes | The resource identifier |
+
+**Query Parameters:**
+
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `limit` | integer | No | 20 | Maximum results to return (1-100) |
+| `cursor` | string | No | — | Pagination cursor from previous response |
+
+**Request Body:**
+
+| Field | Type | Required | Description | Constraints |
+|-------|------|----------|-------------|-------------|
+| `name` | string | Yes | Display name | 1-100 characters |
+| `email` | string | Yes | Email address | Valid email format |
+
+**Example Request:**
+
+\```bash
+curl -X POST https://api.example.com/v1/users \
+  -H "Authorization: Bearer sk-abc123" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Jane Doe",
+    "email": "jane@example.com"
+  }'
+\```
+
+### Response
+
+**Success (201 Created):**
+
+\```json
+{
+  "id": "usr_abc123",
+  "name": "Jane Doe",
+  "email": "jane@example.com",
+  "created_at": "2024-01-15T10:30:00Z"
+}
+\```
+
+**Error Responses:**
+
+| Status | Type | When |
+|--------|------|------|
+| 400 | validation-error | Invalid request body |
+| 401 | authentication-required | Missing or expired token |
+| 409 | resource-conflict | Email already registered |
+| 429 | rate-limit-exceeded | Too many requests |
+```
+
+---
+
+## Parameter Table Format
+
+Always include these columns for parameters:
+
+| Column | Purpose |
+|--------|---------|
+| **Name** | Parameter name as it appears in code |
+| **Type** | Data type (string, integer, boolean, array, object) |
+| **Required** | Yes / No |
+| **Default** | Default value if optional (— if none) |
+| **Description** | What this parameter does |
+| **Constraints** | Validation rules (min/max, regex, enum values) |
+
+### Example
+
+| Name | Type | Required | Default | Description | Constraints |
+|------|------|----------|---------|-------------|-------------|
+| `page_size` | integer | No | 20 | Results per page | 1–100 |
+| `status` | string | No | — | Filter by status | `active`, `inactive`, `pending` |
+| `created_after` | string | No | — | Filter by creation date | ISO 8601 format |
+
+---
+
+## Request / Response Examples
+
+### curl
+
+```bash
+curl -X GET "https://api.example.com/v1/users?status=active&limit=10" \
+  -H "Authorization: Bearer sk-abc123" \
+  -H "Accept: application/json"
+```
+
+### httpie
+
+```bash
+http GET https://api.example.com/v1/users \
+  status==active limit==10 \
+  Authorization:"Bearer sk-abc123"
+```
+
+### Python (requests)
+
+```python
+import requests
+
+response = requests.get(
+    "https://api.example.com/v1/users",
+    params={"status": "active", "limit": 10},
+    headers={"Authorization": "Bearer sk-abc123"},
+)
+data = response.json()
+```
+
+---
+
+## Error Response Documentation
+
+Document every error code an endpoint can return:
+
+```markdown
+### Errors
+
+| Status | Error Type | Description | Example Detail |
+|--------|-----------|-------------|---------------|
+| 400 | `validation-error` | Request body is malformed | "Missing required field: 'name'" |
+| 401 | `authentication-required` | Token missing or expired | "Access token has expired" |
+| 403 | `insufficient-permissions` | Valid token, wrong scope | "Requires 'admin' scope" |
+| 404 | `resource-not-found` | Resource doesn't exist | "No user with ID 'usr_999'" |
+| 409 | `resource-conflict` | Duplicate or state conflict | "Email already registered" |
+| 422 | `unprocessable-entity` | Valid syntax, invalid data | "Age must be positive" |
+| 429 | `rate-limit-exceeded` | Too many requests | "Retry after 30 seconds" |
+```
+
+---
+
+## OpenAPI / Swagger Annotations
+
+### Python (FastAPI)
+
+```python
+@router.post(
+    "/users",
+    response_model=UserResponse,
+    status_code=201,
+    summary="Create a new user",
+    description="Registers a new user account with the provided details.",
+    responses={
+        409: {"description": "Email already registered"},
+        422: {"description": "Validation error"},
+    },
+)
+async def create_user(user: UserCreate) -> UserResponse:
+```
+
+### TypeScript (NestJS / Swagger)
+
+```typescript
+@ApiOperation({ summary: 'Create a new user' })
+@ApiResponse({ status: 201, description: 'User created', type: UserResponse })
+@ApiResponse({ status: 409, description: 'Email already registered' })
+@Post('users')
+async createUser(@Body() dto: CreateUserDto): Promise<UserResponse> {
+```
+
+---
+
+## Mermaid Diagram Quick Reference
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant A as API
+    participant D as Database
+    C->>A: POST /users
+    A->>D: INSERT user
+    D-->>A: user record
+    A-->>C: 201 Created
+```
+
+### Flowchart
+
+```mermaid
+flowchart TD
+    A[Request] --> B{Authenticated?}
+    B -->|No| C[401 Unauthorized]
+    B -->|Yes| D{Valid Input?}
+    D -->|No| E[422 Validation Error]
+    D -->|Yes| F[Process Request]
+    F --> G[200 OK]
+```
+
+### Entity Relationship
+
+```mermaid
+erDiagram
+    USER ||--o{ ORDER : places
+    ORDER ||--|{ LINE_ITEM : contains
+    PRODUCT ||--o{ LINE_ITEM : "ordered in"
+```
+
+### Tips
+
+- Keep diagrams **under 10 nodes**. Split complex flows into multiple diagrams.
+- Use descriptive labels on arrows (not just `-->` but `-->|description|`).
+- Mermaid renders in GitHub, VS Code preview, and most documentation platforms.
+- For architecture diagrams, prefer `flowchart` over `graph` (flowchart is the newer syntax).

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/documentation-patterns/references/docstring-formats.md

@@ -0,0 +1,296 @@
+# Docstring Format Reference
+
+Complete templates for inline documentation across languages. Detect the project's existing style before adding new docstrings.
+
+---
+
+## Python
+
+### Google-Style (Recommended Default)
+
+Detection pattern: `Grep: "Args:"` or `Grep: "Returns:"` in `.py` files.
+
+```python
+def process_payment(amount: float, currency: str, customer_id: str) -> PaymentResult:
+    """Process a payment for the given customer.
+
+    Validates the amount, charges the customer's default payment method,
+    and records the transaction in the payment ledger.
+
+    Args:
+        amount: Payment amount in the smallest currency unit (e.g., cents).
+            Must be positive.
+        currency: ISO 4217 currency code (e.g., "usd", "eur").
+        customer_id: The unique customer identifier from the auth system.
+
+    Returns:
+        PaymentResult with transaction ID, status, and timestamp.
+
+    Raises:
+        InvalidAmountError: If amount is negative or zero.
+        CustomerNotFoundError: If customer_id doesn't match any customer.
+        PaymentGatewayError: If the external payment provider is unreachable.
+
+    Example:
+        >>> result = process_payment(1500, "usd", "cust_abc123")
+        >>> result.status
+        'completed'
+    """
+```
+
+### NumPy-Style
+
+Detection pattern: `Grep: "Parameters\n----------"` (multiline) or `Grep: "----------"` in docstrings.
+
+```python
+def interpolate(x, y, method="linear"):
+    """Interpolate data points using the specified method.
+
+    Parameters
+    ----------
+    x : array_like
+        The x-coordinates of the data points.
+    y : array_like
+        The y-coordinates of the data points. Must have the same length as `x`.
+    method : str, optional
+        Interpolation method. One of 'linear', 'cubic', 'nearest'.
+        Default is 'linear'.
+
+    Returns
+    -------
+    callable
+        An interpolation function that accepts x values and returns
+        interpolated y values.
+
+    Raises
+    ------
+    ValueError
+        If `x` and `y` have different lengths.
+
+    Examples
+    --------
+    >>> f = interpolate([0, 1, 2], [0, 1, 4], method='cubic')
+    >>> f(1.5)
+    2.25
+    """
+```
+
+### Sphinx / reStructuredText
+
+Detection pattern: `Grep: ":param "` or `Grep: ":type "` in `.py` files.
+
+```python
+def connect(host, port, timeout=30):
+    """Connect to the remote server.
+
+    Establishes a TCP connection with configurable timeout.
+
+    :param host: Server hostname or IP address.
+    :type host: str
+    :param port: Server port number (1-65535).
+    :type port: int
+    :param timeout: Connection timeout in seconds. Defaults to 30.
+    :type timeout: int
+    :returns: Active connection handle.
+    :rtype: Connection
+    :raises ConnectionError: If the server is unreachable.
+    :raises ValueError: If port is out of valid range.
+    """
+```
+
+### Module and Class Docstrings
+
+```python
+"""Payment processing module.
+
+Handles payment creation, validation, and gateway communication.
+Supports Stripe and PayPal providers via the adapter pattern.
+
+See `src/payments/adapters/` for provider implementations.
+"""
+
+
+class PaymentProcessor:
+    """Orchestrates payment workflows across multiple providers.
+
+    Manages provider selection, retry logic, and transaction recording.
+    Uses the strategy pattern to delegate provider-specific logic.
+
+    Attributes:
+        default_provider: Name of the fallback payment provider.
+        max_retries: Maximum retry attempts for failed transactions.
+    """
+```
+
+---
+
+## TypeScript / JavaScript
+
+### JSDoc
+
+Detection pattern: `Grep: "@param "` or `Grep: "@returns"` in `.ts` or `.js` files.
+
+```typescript
+/**
+ * Process a payment for the given customer.
+ *
+ * Validates the amount, charges the customer's default payment method,
+ * and records the transaction.
+ *
+ * @param amount - Payment amount in cents (must be positive)
+ * @param currency - ISO 4217 currency code (e.g., "usd", "eur")
+ * @param customerId - The unique customer identifier
+ * @returns Payment result with transaction ID and status
+ * @throws {InvalidAmountError} If amount is negative or zero
+ * @throws {CustomerNotFoundError} If customerId doesn't match any customer
+ *
+ * @example
+ * ```typescript
+ * const result = await processPayment(1500, "usd", "cust_abc123");
+ * console.log(result.status); // "completed"
+ * ```
+ */
+async function processPayment(
+  amount: number,
+  currency: string,
+  customerId: string
+): Promise<PaymentResult> {
+```
+
+### TSDoc
+
+TSDoc is a stricter subset of JSDoc used by TypeScript-focused projects.
+
+Key differences from JSDoc:
+- Uses `{@link ClassName}` for references (not `{@see}`)
+- `@param name -` format (with dash separator)
+- `@throws` without type braces (types are in TypeScript)
+
+```typescript
+/**
+ * Fetches user data from the API.
+ *
+ * @param userId - The user's unique identifier
+ * @param options - Request configuration
+ * @returns The user object, or `undefined` if not found
+ *
+ * @remarks
+ * This method caches results for 5 minutes. Use {@link invalidateCache}
+ * to force a fresh fetch.
+ */
+```
+
+### Module / File Headers
+
+```typescript
+/**
+ * @module payments
+ *
+ * Payment processing module handling Stripe and PayPal integrations.
+ * Entry point: {@link PaymentProcessor.process}
+ */
+```
+
+---
+
+## Go (godoc)
+
+Detection pattern: Comments starting with the function/type name: `Grep: "^// [A-Z]"` before `func` or `type` declarations.
+
+```go
+// ProcessPayment charges the customer's default payment method.
+// Amount is in the smallest currency unit (e.g., cents for USD).
+// Currency must be a valid ISO 4217 code.
+//
+// Returns the transaction result or an error if the charge fails.
+// Possible errors: ErrInvalidAmount, ErrCustomerNotFound, ErrGatewayUnavailable.
+func ProcessPayment(amount int64, currency string, customerID string) (*PaymentResult, error) {
+```
+
+### Package Comments
+
+```go
+// Package payments provides payment processing across multiple providers.
+//
+// It supports Stripe and PayPal via pluggable adapters. Use NewProcessor
+// to create a processor with the desired provider configuration.
+//
+// Example:
+//
+//	p := payments.NewProcessor(payments.WithStripe(apiKey))
+//	result, err := p.Process(ctx, 1500, "usd", "cust_123")
+package payments
+```
+
+### godoc Conventions
+
+- First sentence starts with the name being documented: "ProcessPayment charges..."
+- Use complete sentences with proper punctuation.
+- Code examples use tab-indented blocks (no triple backticks).
+- Document exported (capitalized) identifiers only.
+
+---
+
+## Rust (rustdoc)
+
+Detection pattern: `Grep: "/// "` or `Grep: "//! "` in `.rs` files.
+
+```rust
+/// Process a payment for the given customer.
+///
+/// Validates the amount, charges the customer's default payment method,
+/// and records the transaction in the payment ledger.
+///
+/// # Arguments
+///
+/// * `amount` - Payment amount in cents (must be positive)
+/// * `currency` - ISO 4217 currency code (e.g., "usd", "eur")
+/// * `customer_id` - The unique customer identifier
+///
+/// # Returns
+///
+/// A `PaymentResult` with transaction ID, status, and timestamp.
+///
+/// # Errors
+///
+/// Returns `PaymentError::InvalidAmount` if the amount is zero or negative.
+/// Returns `PaymentError::CustomerNotFound` if the customer ID is invalid.
+///
+/// # Examples
+///
+/// ```
+/// let result = process_payment(1500, "usd", "cust_abc123")?;
+/// assert_eq!(result.status, PaymentStatus::Completed);
+/// ```
+///
+/// # Panics
+///
+/// Panics if the payment gateway client is not initialized. Call
+/// `init_gateway()` before using this function.
+pub fn process_payment(amount: u64, currency: &str, customer_id: &str) -> Result<PaymentResult, PaymentError> {
+```
+
+### Module Documentation
+
+```rust
+//! Payment processing module.
+//!
+//! Handles payment creation, validation, and gateway communication.
+//! Supports Stripe and PayPal providers via the adapter pattern.
+//!
+//! # Overview
+//!
+//! Use [`PaymentProcessor::new`] to create a processor, then call
+//! [`PaymentProcessor::process`] to execute a payment.
+```
+
+### Sections Convention
+
+| Section | When to Use |
+|---------|------------|
+| `# Arguments` | All public functions with parameters |
+| `# Returns` | Functions that return non-unit types |
+| `# Errors` | Functions that return `Result` |
+| `# Panics` | Functions that can panic |
+| `# Safety` | Unsafe functions — document invariants |
+| `# Examples` | Always for public API |

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/migration-patterns/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: migration-patterns
+description: >-
+  This skill should be used when the user asks to "migrate from X to Y",
+  "upgrade to version N", "bump Python version", "upgrade pydantic",
+  "migrate express to fastify", "framework migration", "version upgrade",
+  "modernize the codebase", or discusses code migration, framework upgrades,
+  API version bumps, or dependency migration strategies.
+version: 0.1.0
+---
+
+# Migration Patterns
+
+## Mental Model
+
+Migrations are a sequence of **small, verifiable, rollback-safe transformations**. Each step must independently compile, pass tests, and leave the system in a valid state. The moment you batch changes or skip verification, you create a state that is harder to debug than the original problem.
+
+**Key principles:**
+- **One thing at a time.** Each migration step changes one category of code (imports, API calls, configuration, types). Mixing categories makes failures hard to isolate.
+- **Verify after every step.** Build → Test → Lint after each transformation. A broken intermediate state that goes undetected compounds into an undebuggable mess.
+- **Rollback is always an option.** Git checkpoints after each successful step. If step N fails, you can revert to step N-1 cleanly.
+- **Import mapping first.** Most framework migrations change import paths. Map all imports before modifying call sites — this gives you a complete inventory of affected code.
+- **Official guides are the source of truth.** Always fetch and read the official migration guide before planning. Community blog posts may be outdated or incomplete.
+
+---
+
+## Migration Planning Framework
+
+Follow this sequence for every migration:
+
+### 1. Assess Current State
+
+- Read manifest files to identify current version and all dependencies.
+- Use `Glob` and `Grep` to inventory usage of the APIs being migrated.
+- Count occurrences of each deprecated pattern to estimate effort.
+
+### 2. Read Official Guides
+
+- Use `WebFetch` to pull the official migration guide, changelog, and breaking changes list.
+- Note every breaking change that applies to the project.
+- Identify changes with no direct replacement — these need special handling.
+
+### 3. Inventory Affected Files
+
+- Map every file that uses a deprecated API or pattern.
+- Group files by change type (imports, API calls, configuration, types).
+- Count total changes per group to estimate per-step effort.
+
+### 4. Order Steps
+
+Sequence changes so each step is independently buildable:
+
+1. **Configuration** — Manifest files, build configs, tool configs
+2. **Core utilities and shared modules** — Changes here propagate to dependents
+3. **Business logic** — Module by module, starting with lowest dependency count
+4. **Route handlers / controllers** — Often the most numerous changes
+5. **Tests** — Updated last to match migrated source
+
+### 5. Risk Assessment
+
+Flag high-risk changes:
+- Behavioral changes (same API, different default behavior)
+- Removed APIs with no direct replacement
+- Database schema changes
+- Serialization format changes (affects stored data)
+
+### 6. Present Plan
+
+Output numbered steps with:
+- File count per step
+- Risk level (low / medium / high)
+- Verification command
+- Rollback command
+
+---
+
+## Step Verification Protocol
+
+After each migration step, run these checks in order:
+
+| Check | Command Examples | Purpose |
+|-------|-----------------|---------|
+| **Syntax** | `python -m py_compile`, `npx tsc --noEmit`, `node --check` | Code parses correctly |
+| **Build** | `npm run build`, `cargo build`, `go build ./...` | Project compiles |
+| **Tests** | `pytest`, `npm test`, `cargo test`, `go test ./...` | Behavior preserved |
+| **Lint** | `ruff check`, `npm run lint`, `cargo clippy` | Style and correctness |
+
+If any check fails:
+1. Identify which change in this step caused the failure.
+2. Fix within the current step — do not proceed to the next.
+3. If the fix is unclear, report the failure with full error output.
+4. Never fix forward by making changes intended for later steps.
+
+---
+
+## Rollback Strategy
+
+- **Before starting**: Verify the user has committed or stashed current work.
+- **After each step**: Suggest a commit checkpoint: "Step N complete — recommend committing now."
+- **On failure**: Provide exact `git checkout -- <files>` commands to revert to the last good state.
+- **Database migrations**: Always plan the down-migration alongside the up-migration.
+- **Feature flags**: For gradual migrations, consider feature flags to run old and new code paths in parallel.
+
+---
+
+## Import-First Strategy
+
+Most framework migrations change import paths. Map imports before modifying call sites:
+
+1. **Inventory**: `Grep` for all imports from the old framework/library.
+2. **Map**: Create a mapping of old import → new import.
+3. **Transform**: Change all imports in a single step.
+4. **Verify**: Build and test after import changes (some imports may have side effects).
+5. **Proceed**: With imports correct, modify call sites knowing the right modules are loaded.
+
+This approach gives you a complete inventory of affected code before making any behavioral changes.
+
+---
+
+## Common Pitfalls
+
+| Pitfall | Why It Fails | Prevention |
+|---------|-------------|------------|
+| Batching all changes | One failure breaks everything; can't isolate cause | One category per step |
+| Skipping verification | Errors compound silently | Build + test after every step |
+| Fixing forward | New changes mask existing failures | Fix in current step or revert |
+| Ignoring transitive deps | A dependency may not support the target version | Check compatibility first |
+| Mixing migration with refactoring | Two concerns, double the failure modes | Migrate first, refactor later |
+| Not reading the migration guide | Miss non-obvious behavioral changes | Official guide before planning |
+
+---
+
+## Ambiguity Policy
+
+| Ambiguity | Default |
+|-----------|---------|
+| **Verification depth** | Full suite: build + test + lint after every step |
+| **Step granularity** | One file category per step (imports, then API calls, then config) |
+| **Unknown migration path** | Fetch docs, analyze both APIs, present mapping for review |
+| **Partial migration requested** | Warn about inconsistency; verify the module's own tests pass |
+| **Target version not specified** | Migrate to the latest stable release |
+
+---
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| [Python Migrations](references/python-migrations.md) | Python version upgrades (3.8→3.12), Pydantic v1→v2 API mapping, Django and SQLAlchemy migration patterns |
+| [JavaScript Migrations](references/javascript-migrations.md) | Express→Fastify mapping, React upgrade patterns, TypeScript version upgrades, CommonJS→ESM migration |