codeforge-dev 1.7.0 → 1.8.0

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/dependency-management/references/license-compliance.md

@@ -0,0 +1,80 @@
+# License Compliance Reference
+
+## License Classification
+
+| Category | Licenses | SPDX IDs | Obligations |
+|----------|----------|----------|-------------|
+| **Permissive** | MIT, BSD 2-Clause, BSD 3-Clause, Apache 2.0, ISC, Unlicense, CC0, Zlib | `MIT`, `BSD-2-Clause`, `BSD-3-Clause`, `Apache-2.0`, `ISC`, `Unlicense`, `CC0-1.0`, `Zlib` | Attribution in LICENSE file. Minimal restrictions. |
+| **Weak Copyleft** | LGPL 2.1, LGPL 3.0, MPL 2.0, EPL 2.0 | `LGPL-2.1-only`, `LGPL-3.0-only`, `MPL-2.0`, `EPL-2.0` | Modifications to the library itself must be shared. Using as a dependency is fine. |
+| **Strong Copyleft** | GPL 2.0, GPL 3.0, AGPL 3.0 | `GPL-2.0-only`, `GPL-3.0-only`, `AGPL-3.0-only` | Derivative works must use the same license. AGPL extends to network use. |
+| **Non-Commercial** | CC BY-NC, various | `CC-BY-NC-4.0` | Cannot use in commercial products. |
+| **Unknown / Custom** | Proprietary, no license, custom terms | — | Requires legal review. No license = all rights reserved by default. |
+
+---
+
+## Commercial Usage Implications
+
+### Permissive Licenses (Low Risk)
+
+Safe for all use cases including proprietary/commercial software. Main obligation is preserving copyright notices and license text, typically in a NOTICES or LICENSE file.
+
+Apache 2.0 additionally includes a patent grant — it protects users from patent claims by contributors.
+
+### Weak Copyleft (Medium Risk)
+
+Safe when used as a **library dependency** without modification. If you modify the library's source code, those modifications must be released under the same license. Dynamic linking is generally safe; static linking may trigger copyleft depending on the license.
+
+**MPL 2.0** is file-level copyleft — only modified files need to be shared, not the entire project.
+
+### Strong Copyleft (High Risk)
+
+**GPL**: Any software that links to or includes GPL code may be considered a derivative work, requiring the entire project to be released under GPL. This is incompatible with proprietary/closed-source distribution.
+
+**AGPL**: Same as GPL, but also triggered by providing the software as a network service (SaaS). If users interact with AGPL code over a network, you must provide source code access.
+
+**Impact on SaaS**: AGPL is the highest-risk license for SaaS products. A single AGPL dependency can require releasing your entire service's source code.
+
+### No License / Unknown
+
+Code without a license defaults to **all rights reserved**. You have no legal right to use, modify, or distribute it. Flag these for immediate review and either:
+- Contact the author to request a license
+- Replace the dependency with a licensed alternative
+
+---
+
+## Common License Conflicts
+
+| Combination | Compatible? | Notes |
+|-------------|-------------|-------|
+| MIT + Apache-2.0 | Yes | Both permissive, no conflict |
+| MIT + GPL-3.0 | One-way | GPL project can include MIT code; MIT project cannot include GPL code without becoming GPL |
+| Apache-2.0 + GPL-2.0 | No | Patent clause conflict. Apache-2.0 is compatible with GPL-3.0 but not GPL-2.0 |
+| LGPL + Proprietary | Yes (with care) | Use as a library via dynamic linking. Do not modify LGPL source in your codebase |
+| GPL + Proprietary | No | Cannot combine in a single distributed work |
+| AGPL + SaaS | Problematic | Network use triggers source disclosure |
+| Any + Unlicensed | No | No license = no permission to use |
+
+---
+
+## Recommended Actions by Risk Level
+
+| Risk Level | Action |
+|-----------|--------|
+| **Permissive only** | No action needed. Ensure LICENSE/NOTICES file includes all attributions. |
+| **Weak copyleft present** | Verify the dependency is used as a library without source modifications. Document in compliance notes. |
+| **Strong copyleft present** | Escalate to legal/management. Evaluate whether the dependency can be replaced. Document the dependency chain. |
+| **AGPL in SaaS context** | Treat as critical. Either replace the dependency or prepare for source disclosure. |
+| **Unknown/missing license** | Block the dependency. Do not use code without explicit license grants. |
+| **License changed in update** | Check license changes before upgrading — some packages have changed from permissive to restrictive between versions. |
+
+---
+
+## Detection Patterns
+
+Search for license information in this order:
+1. `LICENSE`, `LICENSE.md`, `LICENSE.txt` in the package root
+2. `license` field in `package.json` (Node.js)
+3. `license` field in `Cargo.toml` (Rust)
+4. `License` classifier in `pyproject.toml` or `setup.py` (Python)
+5. SPDX identifier in source file headers
+6. Package registry metadata (npm registry, PyPI, crates.io)

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

@@ -0,0 +1,153 @@
+---
+name: documentation-patterns
+description: >-
+  This skill should be used when the user asks to "write a README",
+  "write documentation", "add docstrings", "add JSDoc", "document the API",
+  "create architecture docs", "documentation template", "update the docs",
+  or discusses docstring formats, README structure, API documentation,
+  inline comments, or technical writing patterns.
+version: 0.1.0
+---
+
+# Documentation Patterns
+
+## Mental Model
+
+Documentation has **audiences**. README for new users, API docs for integrators, architecture docs for maintainers, inline docs for contributors. Wrong audience = wrong documentation. Before writing, identify who will read it and what they need to accomplish.
+
+**Key principles:**
+- **Accuracy over completeness.** Inaccurate documentation is worse than missing documentation. Only document behavior verified by reading code. Mark uncertainty with `TODO: verify`.
+- **Audience determines format.** A README walks someone through getting started. An API reference lists every parameter with types. An architecture doc explains why decisions were made. Don't mix formats.
+- **Code is the source of truth.** Never copy code into documentation — reference file paths instead. Copied snippets rot as soon as the source changes.
+- **Concise, specific, active voice.** "Returns a list of users" not "A list of users is returned by this function." Cut filler words entirely.
+- **Show, don't tell.** A working example communicates more than three paragraphs of explanation.
+
+---
+
+## Documentation Types and Audiences
+
+| Type | Audience | Purpose | Format |
+|------|----------|---------|--------|
+| **README** | New users, evaluators | What is this? How do I use it? | Markdown, top-level |
+| **API Reference** | Integrators, consumers | Every endpoint/function with types and examples | Markdown or OpenAPI |
+| **Architecture** | Maintainers, new team members | How the system works and why | Markdown with diagrams |
+| **Inline (docstrings)** | Contributors, IDE users | What this function does, parameters, returns | Language-specific format |
+| **Changelog** | Users, upgraders | What changed between versions | Markdown, keep-a-changelog format |
+| **Configuration** | Operators, deployers | All config options with types and defaults | Markdown table or .env.example |
+
+---
+
+## README Structure
+
+Answer five questions, in order:
+
+### 1. What is this?
+
+One paragraph. Project name, what it does, who it is for. No jargon. If someone reads only this paragraph, they should know whether to keep reading.
+
+### 2. How do I install it?
+
+Prerequisites (with exact versions), installation steps, environment setup. Copy-pasteable commands.
+
+### 3. How do I use it?
+
+Quick start example. Show the simplest possible usage that produces a visible result. Include the expected output.
+
+### 4. How do I configure it?
+
+Table of configuration options: name, type, required/optional, default, description. Environment variables, config files, CLI flags.
+
+### 5. How do I contribute?
+
+Development setup, how to run tests, how to submit changes. Link to CONTRIBUTING.md for details.
+
+---
+
+## Sizing Rules
+
+Documentation files consumed by AI tools (CLAUDE.md, specs, architecture docs) should be **≤200 lines** each. Split large documents by concern. Each file should be independently useful.
+
+For human-facing docs (README, API reference), there is no hard limit, but prefer shorter docs that link to detailed sub-pages over monolithic documents.
+
+---
+
+## Style Principles
+
+1. **Concise** — "To configure..." not "In order to configure...". Cut "basically", "simply", "just", "actually".
+2. **Specific** — Use exact types, values, and names. "`api_key` (string, required)" not "pass a key."
+3. **Accurate** — Document only verified behavior. Mark uncertainty with `TODO: verify`.
+4. **Active voice** — "The function returns a list" not "A list is returned."
+5. **Show, don't tell** — Code examples over prose explanations.
+6. **Consistent** — Match the project's existing documentation style for tense, format, and conventions.
+7. **Audience-appropriate** — README uses everyday language. API docs use technical precision. Architecture docs explain rationale.
+
+---
+
+## Inline Documentation Strategy
+
+### When to Document
+
+Document every **public** function, class, and module. Skip private/internal helpers unless their behavior is non-obvious.
+
+Priority order:
+1. Public API functions and methods
+2. Class/module-level docstrings
+3. Complex algorithms (inline comments explaining *why*)
+4. Configuration and constants with non-obvious values
+
+### Style Detection
+
+Before adding docstrings, check which style the project already uses:
+
+```
+# Python — look for existing patterns
+Grep: """    → Google-style or NumPy-style
+Grep: :param → Sphinx/reStructuredText
+Grep: Parameters\n----------  → NumPy-style
+
+# JavaScript/TypeScript
+Grep: @param → JSDoc/TSDoc
+Grep: @returns → JSDoc/TSDoc
+
+# Go
+Grep: ^// [A-Z].*function → godoc convention
+
+# Rust
+Grep: /// → rustdoc
+Grep: //! → module-level rustdoc
+```
+
+Follow the existing style. If no docstrings exist, use the language's recommended default.
+
+---
+
+## Verification
+
+Before finalizing documentation:
+
+1. **Every command is correct** — Try running install commands, API examples, and code snippets against the actual project.
+2. **Every path exists** — Reference only files that actually exist in the codebase.
+3. **Every parameter matches the code** — Check function signatures against the documented parameters.
+4. **Links work** — Verify internal references and external URLs.
+5. **Version numbers are current** — Check package versions in install commands.
+
+---
+
+## Ambiguity Policy
+
+| Ambiguity | Default |
+|-----------|---------|
+| **Audience not specified** | Write for the most common audience for the doc type (README → new users, docstrings → contributors) |
+| **Scope not specified** | Document the public API surface; skip internals |
+| **Format not specified** | Follow existing project conventions; fall back to language defaults |
+| **Level of detail** | Include parameters, return values, and one example per function |
+| **Behavior uncertain** | Mark with `TODO: verify — [specific question]` rather than guessing |
+
+---
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| [Docstring Formats](references/docstring-formats.md) | Complete templates for Python (Google, NumPy, Sphinx), TypeScript/JavaScript (JSDoc, TSDoc), Go (godoc), and Rust (rustdoc) with detection patterns |
+| [API Doc Templates](references/api-doc-templates.md) | REST endpoint documentation template, request/response examples, parameter tables, error documentation, OpenAPI annotation patterns, and Mermaid diagram quick reference |

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).