codeforge-dev 1.7.0 → 1.8.0

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/api-design/references/rest-conventions.md

@@ -0,0 +1,215 @@
+# REST Conventions Reference
+
+## HTTP Method Semantics
+
+### GET — Read Resources
+
+- Retrieves a resource or collection. Never modifies state.
+- **Cacheable** by default. Use `Cache-Control` and `ETag` headers.
+- Collection: `GET /users` → `200 OK` with array
+- Single: `GET /users/123` → `200 OK` with object, or `404 Not Found`
+
+### POST — Create Resources
+
+- Creates a new resource. The server assigns the ID.
+- **Not idempotent** — repeating the request creates duplicate resources.
+- Response: `201 Created` with `Location` header pointing to the new resource.
+- Include the created resource in the response body.
+
+### PUT — Full Replace
+
+- Replaces the entire resource. Client sends the complete representation.
+- **Idempotent** — repeating the request produces the same state.
+- If the resource doesn't exist: return `404` (don't auto-create unless designed for upsert).
+- Response: `200 OK` with the updated resource.
+
+### PATCH — Partial Update
+
+- Modifies specific fields without replacing the entire resource.
+- Use JSON Merge Patch (`Content-Type: application/merge-patch+json`) for simplicity.
+- Response: `200 OK` with the complete updated resource.
+- Omitted fields remain unchanged.
+
+### DELETE — Remove Resources
+
+- Removes a resource.
+- **Idempotent** — deleting an already-deleted resource returns `204` or `404` (both are valid, be consistent).
+- Response: `204 No Content` (no body).
+
+### HEAD — Headers Only
+
+- Identical to GET but returns no body. Used for checking existence, content length, or cache validity.
+
+### OPTIONS — Capabilities
+
+- Returns allowed methods and CORS headers. Response: `204 No Content` with `Allow` header.
+
+---
+
+## Status Code Reference
+
+### 2xx — Success
+
+| Code | Name | When to Use |
+|------|------|------------|
+| `200` | OK | GET, PUT, PATCH succeeded. General success. |
+| `201` | Created | POST created a resource. Include `Location` header. |
+| `202` | Accepted | Request accepted for async processing. Include status URL. |
+| `204` | No Content | DELETE succeeded. OPTIONS response. No body. |
+
+### 3xx — Redirection
+
+| Code | Name | When to Use |
+|------|------|------------|
+| `301` | Moved Permanently | Resource URL changed permanently. Clients should update. |
+| `302` | Found | Temporary redirect. Original URL still valid. |
+| `304` | Not Modified | Cache is still valid. Response to conditional GET. |
+
+### 4xx — Client Errors
+
+| Code | Name | When to Use |
+|------|------|------------|
+| `400` | Bad Request | Malformed syntax, invalid JSON, missing required fields. |
+| `401` | Unauthorized | No credentials or invalid/expired credentials. |
+| `403` | Forbidden | Valid credentials but insufficient permissions. |
+| `404` | Not Found | Resource doesn't exist. |
+| `405` | Method Not Allowed | HTTP method not supported for this URL. Include `Allow` header. |
+| `409` | Conflict | State conflict (duplicate, version mismatch, concurrent modification). |
+| `410` | Gone | Resource existed but was permanently deleted. |
+| `415` | Unsupported Media Type | Content-Type not supported. |
+| `422` | Unprocessable Entity | Valid syntax but semantic errors (validation failures). |
+| `429` | Too Many Requests | Rate limit exceeded. Include `Retry-After` header. |
+
+### 5xx — Server Errors
+
+| Code | Name | When to Use |
+|------|------|------------|
+| `500` | Internal Server Error | Unhandled exception. Log the error, return generic message. |
+| `502` | Bad Gateway | Upstream service returned invalid response. |
+| `503` | Service Unavailable | Server overloaded or in maintenance. Include `Retry-After`. |
+| `504` | Gateway Timeout | Upstream service did not respond in time. |
+
+---
+
+## Resource Naming Conventions
+
+### Collection Patterns
+
+```
+/users                    → User collection
+/users/{id}               → Specific user
+/users/{id}/orders        → Orders belonging to a user
+/users/{id}/orders/{oid}  → Specific order of a user
+```
+
+### Naming Rules
+
+- **Plural nouns** for collections: `/users`, not `/user`
+- **Lowercase with hyphens** for multi-word: `/order-items`, not `/orderItems` or `/order_items`
+- **No trailing slashes**: `/users`, not `/users/`
+- **No file extensions**: `/users/123`, not `/users/123.json`
+- **No verbs**: `/users/{id}/activate` is acceptable as an action endpoint (RPC-style), but prefer state changes via PATCH when possible
+
+### Action Endpoints (RPC-Style)
+
+When a RESTful mapping is awkward, use action sub-resources:
+
+```
+POST /users/{id}/activate     → Activate a user
+POST /orders/{id}/cancel      → Cancel an order
+POST /emails/{id}/resend      → Resend an email
+```
+
+Action endpoints are always POST (they change state and are not idempotent).
+
+---
+
+## Query Parameter Patterns
+
+### Filtering
+
+```
+GET /users?status=active
+GET /users?role=admin&status=active
+GET /orders?created_after=2024-01-01&created_before=2024-12-31
+```
+
+Use `snake_case` for parameter names. Support multiple values with comma separation or repeated params:
+```
+GET /users?role=admin,editor       (comma-separated)
+GET /users?role=admin&role=editor  (repeated)
+```
+
+### Sorting
+
+```
+GET /users?sort_by=created_at&sort_order=desc
+GET /users?sort=-created_at,name   (prefix - for descending)
+```
+
+### Field Selection
+
+```
+GET /users?fields=id,name,email
+GET /users/{id}?fields=id,name,email,orders
+```
+
+Reduces payload size. Particularly valuable for mobile clients or list views.
+
+### Search
+
+```
+GET /users?q=john                     (full-text search)
+GET /users?name_contains=john         (field-specific search)
+```
+
+---
+
+## Content Negotiation
+
+### Request Headers
+
+```
+Content-Type: application/json        → Request body format
+Accept: application/json              → Desired response format
+Accept-Language: en-US                → Preferred language
+```
+
+### Response Headers
+
+```
+Content-Type: application/json; charset=utf-8
+Content-Length: 1234
+ETag: "abc123"
+Cache-Control: max-age=3600
+```
+
+### Versioned Media Types
+
+```
+Accept: application/vnd.myapi.v2+json
+```
+
+An alternative to URL path versioning. The server reads the Accept header to determine which version to serve.
+
+---
+
+## HATEOAS (Hypermedia)
+
+Include links to related resources and actions in responses:
+
+```json
+{
+  "id": 123,
+  "name": "Jane Doe",
+  "links": {
+    "self": "/users/123",
+    "orders": "/users/123/orders",
+    "activate": "/users/123/activate"
+  }
+}
+```
+
+**When it is worth it**: Public APIs consumed by many third-party clients. The links enable discoverability without hardcoding URL patterns.
+
+**When it is over-engineering**: Internal APIs where clients are maintained by the same team. The added payload and complexity rarely justify the benefit.

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

@@ -0,0 +1,211 @@
+---
+name: ast-grep-patterns
+description: >-
+  This skill should be used when the user asks to "use ast-grep",
+  "structural search", "syntax-aware search", "find code patterns",
+  "search with ast-grep", "use tree-sitter", "find function calls structurally",
+  or discusses ast-grep patterns, structural code search, meta-variables,
+  tree-sitter parsing, or syntax-aware code matching.
+version: 0.1.0
+---
+
+# AST-Grep Patterns
+
+## Mental Model
+
+Text search finds **strings**. Structural search finds **code constructs**. When you need to find all calls to `fetch()` regardless of arguments, a regex like `fetch\(.*\)` matches strings inside comments, string literals, and variable names containing "fetch." ast-grep matches the actual function call in the syntax tree.
+
+**When to use which tool:**
+
+| Need | Tool | Why |
+|------|------|-----|
+| Simple text or identifier | `Grep` | Fastest for literal text matching |
+| Code pattern with variable parts | `ast-grep` (`sg`) | Understands syntax, ignores comments/strings |
+| Full parse tree or all symbols | `tree-sitter` | Deepest structural insight per file |
+| File names by pattern | `Glob` | Path-based discovery |
+
+**Default to Grep** for simple searches. Escalate to ast-grep when:
+- The pattern has variable sub-expressions (any arguments, any name)
+- You need to distinguish code from comments/strings
+- The pattern spans multiple syntax elements (function with decorator, class with method)
+
+---
+
+## Meta-Variable Reference
+
+ast-grep uses meta-variables to match parts of the syntax tree:
+
+| Syntax | Meaning | Example |
+|--------|---------|---------|
+| `$NAME` | Matches exactly one AST node | `console.log($MSG)` matches `console.log("hi")` |
+| `$$$ARGS` | Matches zero or more nodes (variadic) | `func($$$ARGS)` matches `func()`, `func(a)`, `func(a, b, c)` |
+| `$_` | Wildcard — matches one node, not captured | `if ($_ ) { $$$BODY }` matches any if-statement |
+
+**Key distinctions:**
+- `$X` captures and can be referenced — use when you care about what matched
+- `$_` is a throwaway — use when you just need "something here"
+- `$$$X` is greedy — it captures everything between fixed anchors
+
+---
+
+## Tool Invocation
+
+### ast-grep (`sg`)
+
+```bash
+# Basic pattern search
+sg run -p 'PATTERN' -l LANGUAGE
+
+# Search in specific directory
+sg run -p 'PATTERN' -l LANGUAGE path/to/dir/
+
+# With JSON output for parsing
+sg run -p 'PATTERN' -l LANGUAGE --json
+```
+
+**Language identifiers**: `python`, `javascript`, `typescript`, `go`, `rust`, `java`, `c`, `cpp`, `css`, `html`
+
+### tree-sitter
+
+```bash
+# Extract all definitions (functions, classes, methods)
+tree-sitter tags /path/to/file.py
+
+# Parse file and show syntax tree
+tree-sitter parse /path/to/file.py
+
+# Parse and show tree for specific language
+tree-sitter parse --language python /path/to/file.py
+```
+
+---
+
+## Common Cross-Language Patterns
+
+### Function Calls
+
+```bash
+# Any call to a specific function
+sg run -p 'fetch($$$ARGS)' -l javascript
+
+# Method call on any object
+sg run -p '$OBJ.save($$$ARGS)' -l python
+
+# Chained method calls
+sg run -p '$OBJ.filter($$$A).map($$$B)' -l javascript
+```
+
+### Function/Method Definitions
+
+```bash
+# Python function
+sg run -p 'def $NAME($$$PARAMS): $$$BODY' -l python
+
+# Async Python function
+sg run -p 'async def $NAME($$$PARAMS): $$$BODY' -l python
+
+# JavaScript/TypeScript function
+sg run -p 'function $NAME($$$PARAMS) { $$$BODY }' -l javascript
+
+# Arrow function assigned to variable
+sg run -p 'const $NAME = ($$$PARAMS) => $$$BODY' -l javascript
+```
+
+### Import Statements
+
+```bash
+# Python imports
+sg run -p 'from $MODULE import $$$NAMES' -l python
+sg run -p 'import $MODULE' -l python
+
+# JavaScript/TypeScript imports
+sg run -p 'import $$$NAMES from "$MODULE"' -l javascript
+sg run -p 'import { $$$NAMES } from "$MODULE"' -l typescript
+```
+
+### Class Definitions
+
+```bash
+# Python class
+sg run -p 'class $NAME($$$BASES): $$$BODY' -l python
+
+# TypeScript class
+sg run -p 'class $NAME { $$$BODY }' -l typescript
+
+# Class with extends
+sg run -p 'class $NAME extends $BASE { $$$BODY }' -l typescript
+```
+
+### Error Handling
+
+```bash
+# Python try/except
+sg run -p 'try: $$$TRY except $EXCEPTION: $$$EXCEPT' -l python
+
+# JavaScript try/catch
+sg run -p 'try { $$$TRY } catch ($ERR) { $$$CATCH }' -l javascript
+```
+
+### Decorators / Attributes
+
+```bash
+# Python decorator
+sg run -p '@$DECORATOR def $NAME($$$PARAMS): $$$BODY' -l python
+
+# Specific decorator
+sg run -p '@app.route($$$ARGS) def $NAME($$$PARAMS): $$$BODY' -l python
+
+# TypeScript decorator
+sg run -p '@$DECORATOR class $NAME { $$$BODY }' -l typescript
+```
+
+---
+
+## Combining Tools
+
+Use ast-grep for structural finding, then Grep and Read for context:
+
+1. **Find structurally**: `sg run -p 'pattern' -l lang` → get file paths and line numbers
+2. **Filter textually**: Use `Grep` on the results to narrow by specific strings
+3. **Read context**: Use `Read` to examine surrounding code for the matches
+
+Example workflow — find all Express route handlers that don't have error handling:
+
+```bash
+# Step 1: Find all route handlers
+sg run -p 'app.$METHOD($PATH, $$$HANDLERS)' -l javascript
+
+# Step 2: Check which handlers lack try/catch (use Grep on matched files)
+# Grep for the handler function names, then check for try/catch blocks
+
+# Step 3: Read the full handler to confirm
+```
+
+---
+
+## tree-sitter Integration
+
+Use `tree-sitter` when you need the full syntax tree, not just pattern matches:
+
+- **`tree-sitter tags`** — Extracts all definitions (functions, classes, methods, variables) from a file. Use for getting a file's API surface quickly.
+- **`tree-sitter parse`** — Shows the complete syntax tree. Use for debugging ast-grep patterns that don't match as expected, or for understanding unfamiliar syntax.
+
+---
+
+## Ambiguity Policy
+
+| Ambiguity | Default |
+|-----------|---------|
+| **Search tool not specified** | Use Grep for simple text; ast-grep for structural patterns |
+| **Language not specified** | Infer from file extensions in the search directory |
+| **Pattern too broad** | Narrow by directory first, then refine the pattern |
+| **No results from ast-grep** | Fall back to Grep — the pattern may not match the exact syntax tree structure |
+| **Complex nested pattern** | Break into simpler patterns and combine results |
+
+---
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| [Language Patterns](references/language-patterns.md) | Complete pattern catalog for Python, TypeScript/JavaScript, Go, and Rust — function calls, class definitions, imports, async patterns, and more with exact `sg` commands |