codeforge-dev 1.7.0 → 1.8.0

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/scripts/todo-harvester.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""
+TODO/FIXME harvester — SessionStart hook that surfaces tech debt markers.
+
+Greps the codebase for TODO/FIXME/HACK/XXX comments and injects a count
+plus the top items as additionalContext so Claude can proactively mention
+tech debt when relevant.
+
+Reads hook input from stdin (JSON). Returns JSON on stdout.
+Always exits 0 (advisory, never blocking).
+"""
+
+import json
+import os
+import subprocess
+import sys
+
+GREP_TIMEOUT = 5
+MAX_ITEMS = 10
+TOTAL_OUTPUT_CAP = 800
+
+SOURCE_INCLUDES = [
+    "--include=*.py",
+    "--include=*.ts",
+    "--include=*.tsx",
+    "--include=*.js",
+    "--include=*.jsx",
+    "--include=*.go",
+    "--include=*.rs",
+    "--include=*.sh",
+    "--include=*.svelte",
+    "--include=*.vue",
+    "--include=*.rb",
+    "--include=*.java",
+    "--include=*.kt",
+]
+
+EXCLUDE_DIRS = [
+    "--exclude-dir=node_modules",
+    "--exclude-dir=.git",
+    "--exclude-dir=__pycache__",
+    "--exclude-dir=.venv",
+    "--exclude-dir=venv",
+    "--exclude-dir=dist",
+    "--exclude-dir=build",
+    "--exclude-dir=vendor",
+    "--exclude-dir=.next",
+    "--exclude-dir=.nuxt",
+    "--exclude-dir=target",
+    "--exclude-dir=.mypy_cache",
+    "--exclude-dir=.pytest_cache",
+]
+
+
+def main():
+    try:
+        json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        pass
+
+    cwd = os.getcwd()
+
+    cmd = (
+        ["grep", "-rn", "-E", r"\b(TODO|FIXME|HACK|XXX)\b"]
+        + SOURCE_INCLUDES
+        + EXCLUDE_DIRS
+        + [cwd]
+    )
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=GREP_TIMEOUT,
+        )
+    except (FileNotFoundError, OSError, subprocess.TimeoutExpired):
+        sys.exit(0)
+
+    # grep returns 1 for no matches — that's fine
+    output = result.stdout.strip()
+    if not output:
+        sys.exit(0)
+
+    lines = output.splitlines()
+    total_count = len(lines)
+
+    # Count unique files
+    files_seen: set[str] = set()
+    items: list[str] = []
+
+    for line in lines:
+        # Format: filepath:linenum:content
+        parts = line.split(":", 2)
+        if len(parts) >= 3:
+            filepath = parts[0]
+            files_seen.add(filepath)
+
+            if len(items) < MAX_ITEMS:
+                # Make path relative to cwd for readability
+                rel_path = os.path.relpath(filepath, cwd)
+                line_num = parts[1]
+                content = parts[2].strip()
+
+                # Trim long lines
+                if len(content) > 80:
+                    content = content[:77] + "..."
+
+                items.append(f"  {rel_path}:{line_num}: {content}")
+
+    file_count = len(files_seen)
+    header = (
+        f"[Tech Debt] {total_count} TODO/FIXME items found across {file_count} files"
+    )
+
+    if items:
+        body = header + "\nTop items:\n" + "\n".join(items)
+    else:
+        body = header
+
+    # Cap total output
+    if len(body) > TOTAL_OUTPUT_CAP:
+        body = body[:TOTAL_OUTPUT_CAP] + "\n...(truncated)"
+
+    json.dump({"additionalContext": body}, sys.stdout)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/api-design/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: api-design
+description: >-
+  This skill should be used when the user asks to "design an API",
+  "design REST endpoints", "plan API versioning", "choose pagination strategy",
+  "design error responses", "API conventions", "endpoint design",
+  "create API documentation", or discusses REST API design, HTTP method
+  semantics, status code selection, authentication patterns, or rate limiting.
+version: 0.1.0
+---
+
+# API Design
+
+## Mental Model
+
+APIs are **contracts**. Once published, they are promises to consumers. Design for the consumer, not the implementation. Consistency beats cleverness — a predictable API with simple conventions is easier to use than a clever API with special cases.
+
+**Key principles:**
+- **Resources, not actions.** URLs name things (`/users`, `/orders`), HTTP methods express actions (GET, POST, PUT, DELETE). Verbs in URLs signal a design problem.
+- **Consistency above all.** If one endpoint uses `snake_case`, all endpoints use `snake_case`. If one endpoint paginates with `cursor`, all endpoints paginate with `cursor`.
+- **Explicit over implicit.** Document every behavior. Default values, sort orders, pagination limits — if a consumer has to guess, the API is underspecified.
+- **Idempotency by design.** GET, PUT, DELETE are idempotent. POST creates new resources. Design operations so repeating a request does not produce unexpected side effects.
+
+---
+
+## Resource Naming
+
+Use plural nouns for collections, singular identifiers for individual resources:
+
+```
+GET    /users          → List users
+POST   /users          → Create a user
+GET    /users/{id}     → Get a specific user
+PUT    /users/{id}     → Replace a user
+PATCH  /users/{id}     → Partially update a user
+DELETE /users/{id}     → Delete a user
+```
+
+**Nested resources** for clear ownership:
+```
+GET    /users/{id}/orders       → List orders for a user
+POST   /users/{id}/orders       → Create an order for a user
+GET    /users/{id}/orders/{oid} → Get a specific order
+```
+
+Limit nesting to 2 levels. Beyond that, promote the resource to a top-level endpoint with a query filter: `/orders?user_id=123`.
+
+**Naming rules:**
+- Use `kebab-case` for multi-word paths: `/order-items`, not `/orderItems`
+- Use `snake_case` for query parameters: `?sort_by=created_at`
+- Use `snake_case` for JSON fields (aligns with Python/Ruby; for JavaScript-heavy APIs, `camelCase` is also acceptable — pick one and be consistent)
+
+---
+
+## HTTP Method Semantics
+
+| Method | Purpose | Idempotent | Request Body | Success Code |
+|--------|---------|-----------|-------------|-------------|
+| **GET** | Read resource(s) | Yes | No | 200 |
+| **POST** | Create resource | No | Yes | 201 |
+| **PUT** | Full replace | Yes | Yes | 200 |
+| **PATCH** | Partial update | No* | Yes | 200 |
+| **DELETE** | Remove resource | Yes | No | 204 |
+| **HEAD** | Headers only (like GET) | Yes | No | 200 |
+| **OPTIONS** | Describe capabilities | Yes | No | 204 |
+
+*PATCH is idempotent if using JSON Merge Patch; not idempotent with JSON Patch operations.
+
+---
+
+## Pagination Patterns
+
+### Cursor-Based (Recommended)
+
+Best for real-time data, large datasets, and stable traversal:
+
+```json
+GET /users?cursor=eyJpZCI6MTIzfQ&limit=20
+
+{
+  "data": [...],
+  "pagination": {
+    "next_cursor": "eyJpZCI6MTQzfQ",
+    "has_more": true
+  }
+}
+```
+
+Cursors are opaque tokens (base64-encoded state). Consumers pass them back unchanged.
+
+### Offset-Based
+
+Simpler but unstable under concurrent writes:
+
+```json
+GET /users?offset=40&limit=20
+
+{
+  "data": [...],
+  "pagination": {
+    "offset": 40,
+    "limit": 20,
+    "total": 156
+  }
+}
+```
+
+### Decision Framework
+
+| Factor | Cursor | Offset |
+|--------|--------|--------|
+| Data stability | Handles inserts/deletes during pagination | Rows shift when data changes |
+| Performance at scale | O(1) per page | O(n) for large offsets |
+| "Jump to page N" | Not supported | Supported |
+| Implementation complexity | Higher | Lower |
+
+**Default**: Cursor pagination for new APIs. Offset only when consumers explicitly need page-number navigation.
+
+---
+
+## Versioning
+
+### URL Path Versioning (Recommended)
+
+```
+/v1/users
+/v2/users
+```
+
+Visible in every request. Easy to route, test, and document. Most widely understood.
+
+### Header Versioning
+
+```
+Accept: application/vnd.api+json; version=2
+```
+
+Cleaner URLs but harder to test (can't bookmark/share versioned URLs) and harder to route.
+
+### Decision Framework
+
+| Factor | URL Path | Header |
+|--------|----------|--------|
+| Discoverability | High — visible in URL | Low — hidden in headers |
+| Cacheability | Easy — URL-based caching | Requires Vary header |
+| Testing | Easy — curl/browser | Requires setting headers |
+| Aesthetics | "Ugly" URLs | Clean URLs |
+
+**Default**: URL path versioning. It is the most pragmatic choice for most APIs.
+
+---
+
+## Authentication Patterns
+
+| Pattern | Best For | Considerations |
+|---------|----------|---------------|
+| **API Keys** | Server-to-server, simple integrations | Easy to implement. No expiry by default — rotate regularly. Send via header (`X-API-Key` or `Authorization: Bearer`), never in URL. |
+| **JWT (Bearer Tokens)** | Stateless auth, microservices | Self-contained claims. Set short expiry (15-60 min) + refresh tokens. Verify signature and expiry on every request. |
+| **OAuth 2.0** | Third-party integrations, user consent | Authorization Code flow for web apps, Client Credentials for machine-to-machine. Use PKCE for public clients. |
+| **Session Cookies** | Browser-based web apps | Set `HttpOnly`, `Secure`, `SameSite=Strict`. CSRF protection required. |
+
+**Default**: JWT for APIs consumed by multiple clients. API keys for simple server-to-server integrations.
+
+---
+
+## Rate Limiting
+
+### Token Bucket (Recommended)
+
+Allows bursts up to bucket size, then enforces sustained rate:
+- Bucket holds N tokens (e.g., 100)
+- Tokens refill at R per second (e.g., 10/s)
+- Each request costs 1 token (or more for expensive operations)
+
+### Response Headers
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 42
+X-RateLimit-Reset: 1640000000
+Retry-After: 30
+```
+
+Return `429 Too Many Requests` with `Retry-After` header when limit is exceeded.
+
+---
+
+## API Design Checklist
+
+Before implementing, verify:
+
+- [ ] Every endpoint uses a plural noun (not a verb) in the URL
+- [ ] HTTP methods match their semantic purpose
+- [ ] Response format is consistent across all endpoints
+- [ ] Error responses follow a standard format (see reference)
+- [ ] Pagination strategy is consistent across all list endpoints
+- [ ] Authentication mechanism is documented
+- [ ] Rate limits are defined and communicated via headers
+- [ ] Versioning strategy is chosen and applied
+- [ ] All parameters have documented types, constraints, and defaults
+- [ ] Idempotency behavior is documented for each endpoint
+
+---
+
+## Ambiguity Policy
+
+| Ambiguity | Default |
+|-----------|---------|
+| **API style** | REST with JSON request/response bodies |
+| **Pagination** | Cursor-based with `limit` parameter (default 20, max 100) |
+| **Versioning** | URL path versioning (`/v1/`) |
+| **Naming convention** | `snake_case` for JSON fields, `kebab-case` for URL paths |
+| **Auth pattern** | JWT Bearer tokens (unless server-to-server, then API keys) |
+| **Error format** | RFC 7807 Problem Details |
+| **Rate limiting** | Token bucket with standard headers |
+
+---
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| [REST Conventions](references/rest-conventions.md) | Complete HTTP method semantics, status code reference by category, resource naming examples, query parameter patterns, content negotiation, and HATEOAS guidance |
+| [Error Handling](references/error-handling.md) | RFC 7807 Problem Details format, error code taxonomy, consistency rules, client-vs-server error exposure, and retry guidance headers |

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/api-design/references/error-handling.md

@@ -0,0 +1,166 @@
+# API Error Handling Reference
+
+## RFC 7807 Problem Details
+
+The standard format for HTTP API error responses. Use `application/problem+json` as the content type.
+
+### Format
+
+```json
+{
+  "type": "https://api.example.com/errors/validation-error",
+  "title": "Validation Error",
+  "status": 422,
+  "detail": "The 'email' field must be a valid email address.",
+  "instance": "/users/signup",
+  "errors": [
+    {
+      "field": "email",
+      "message": "Must be a valid email address",
+      "value": "not-an-email"
+    }
+  ]
+}
+```
+
+### Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `type` | Yes | URI reference identifying the error type. Use a stable URL (can be a documentation page). |
+| `title` | Yes | Short human-readable summary. Same for all instances of this error type. |
+| `status` | Yes | HTTP status code (repeated from response for convenience). |
+| `detail` | Yes | Human-readable explanation specific to this occurrence. |
+| `instance` | No | URI identifying the specific occurrence (request path or trace ID). |
+
+Extension fields (like `errors` for validation) are allowed and encouraged for structured detail.
+
+---
+
+## Error Code Taxonomy
+
+Organize errors into categories with consistent type URIs:
+
+### Validation Errors (400 / 422)
+
+```json
+{
+  "type": "https://api.example.com/errors/validation-error",
+  "title": "Validation Error",
+  "status": 422,
+  "detail": "Request body contains invalid fields.",
+  "errors": [
+    { "field": "email", "message": "Required field is missing" },
+    { "field": "age", "message": "Must be a positive integer", "value": -5 }
+  ]
+}
+```
+
+Use `422` for semantic validation failures (valid JSON but invalid data). Use `400` for malformed requests (invalid JSON, wrong content type).
+
+### Authentication Errors (401)
+
+```json
+{
+  "type": "https://api.example.com/errors/authentication-required",
+  "title": "Authentication Required",
+  "status": 401,
+  "detail": "The access token has expired. Request a new token."
+}
+```
+
+Always include `WWW-Authenticate` header with 401 responses.
+
+### Authorization Errors (403)
+
+```json
+{
+  "type": "https://api.example.com/errors/insufficient-permissions",
+  "title": "Insufficient Permissions",
+  "status": 403,
+  "detail": "Your API key does not have access to the 'admin' scope."
+}
+```
+
+### Not Found (404)
+
+```json
+{
+  "type": "https://api.example.com/errors/resource-not-found",
+  "title": "Resource Not Found",
+  "status": 404,
+  "detail": "No user found with ID '999'."
+}
+```
+
+### Conflict (409)
+
+```json
+{
+  "type": "https://api.example.com/errors/resource-conflict",
+  "title": "Resource Conflict",
+  "status": 409,
+  "detail": "A user with email 'jane@example.com' already exists."
+}
+```
+
+### Rate Limit (429)
+
+```json
+{
+  "type": "https://api.example.com/errors/rate-limit-exceeded",
+  "title": "Rate Limit Exceeded",
+  "status": 429,
+  "detail": "You have exceeded 100 requests per minute. Try again in 30 seconds."
+}
+```
+
+Always include `Retry-After` header (seconds or HTTP-date).
+
+### Internal Error (500)
+
+```json
+{
+  "type": "https://api.example.com/errors/internal-error",
+  "title": "Internal Server Error",
+  "status": 500,
+  "detail": "An unexpected error occurred. Reference: trace-abc123."
+}
+```
+
+---
+
+## Error Response Consistency Rules
+
+1. **Same shape, always.** Every error response uses the same top-level structure. Consumers should never need to handle different error formats.
+2. **Match status code to error.** The `status` field in the body matches the HTTP status code. Never return `200 OK` with an error body.
+3. **Human-readable details.** The `detail` field should help the consumer fix the problem. "Invalid request" is useless. "The 'email' field must be a valid email address" is actionable.
+4. **Machine-readable type.** The `type` URI enables programmatic error handling. Consumers can switch on the type without parsing the detail string.
+5. **No stack traces in production.** Internal error details (stack traces, database errors, internal paths) are logged server-side. Clients receive a reference ID to correlate with server logs.
+
+---
+
+## Error Logging vs. Error Exposure
+
+| Information | Log Server-Side | Return to Client |
+|-------------|----------------|-----------------|
+| Stack trace | Yes | No |
+| Database error messages | Yes | No |
+| Internal file paths | Yes | No |
+| Request ID / trace ID | Yes | Yes (in `instance` or `detail`) |
+| Validation errors | Yes | Yes (specific field-level errors) |
+| Rate limit status | Yes | Yes (via headers + body) |
+| Business rule violations | Yes | Yes (as actionable `detail`) |
+
+---
+
+## Retry Guidance Headers
+
+| Header | Purpose | Format |
+|--------|---------|--------|
+| `Retry-After` | When to retry after 429 or 503 | Seconds (`30`) or HTTP-date (`Wed, 21 Oct 2025 07:28:00 GMT`) |
+| `X-RateLimit-Limit` | Maximum requests allowed in window | Integer (`100`) |
+| `X-RateLimit-Remaining` | Requests remaining in current window | Integer (`42`) |
+| `X-RateLimit-Reset` | Unix timestamp when window resets | Integer (`1640000000`) |
+
+Include all rate limit headers on **every response** (not just 429s) so clients can proactively manage their request rate.