codeforge-dev 1.7.0 → 1.9.0

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/dependency-management/references/ecosystem-commands.md

@@ -0,0 +1,264 @@
+# Ecosystem Commands Reference
+
+Per-ecosystem command reference for dependency analysis. All commands are **read-only** — they inspect but never modify the project.
+
+If a command is not found, note it as unavailable and skip. Do not attempt to install tools.
+
+---
+
+## Node.js (npm / yarn / pnpm)
+
+### Outdated Packages
+
+```bash
+# npm
+npm outdated 2>/dev/null || true
+
+# yarn
+yarn outdated 2>/dev/null || true
+
+# pnpm
+pnpm outdated 2>/dev/null || true
+```
+
+Output columns: Package, Current, Wanted (semver-compatible), Latest (newest).
+
+### Security Audit
+
+```bash
+# npm — structured output for parsing
+npm audit --json 2>/dev/null || true
+
+# npm — human-readable summary
+npm audit 2>/dev/null || true
+
+# yarn
+yarn audit 2>/dev/null || true
+
+# pnpm
+pnpm audit 2>/dev/null || true
+```
+
+### Unused Detection
+
+No built-in command. Cross-reference `package.json` dependencies with source imports:
+
+```bash
+# List declared dependencies
+node -e "const p=require('./package.json'); console.log(Object.keys(p.dependencies||{}).join('\n'))"
+
+# Search for imports (use Grep tool, not bash grep)
+# Pattern: require('pkg') or import ... from 'pkg'
+```
+
+Known exceptions to flag as "verify manually":
+- `@types/*` packages — TypeScript type definitions, no runtime import
+- Packages in `devDependencies` used only by build/test tooling
+- Babel/ESLint/Prettier plugins loaded by configuration
+- `dotenv` and similar packages loaded via `-r` flag or preload
+
+### Version Conflicts
+
+```bash
+# Check for peer dependency issues
+npm ls 2>&1 | head -100 || true
+
+# Check for duplicated packages
+npm ls --all 2>/dev/null | head -200 || true
+```
+
+### License Listing
+
+```bash
+# Using npx (no install needed)
+npx license-checker --summary 2>/dev/null || true
+
+# Detailed per-package
+npx license-checker --json 2>/dev/null || true
+```
+
+---
+
+## Python (pip / uv / poetry)
+
+### Outdated Packages
+
+```bash
+# pip
+pip list --outdated 2>/dev/null || true
+
+# uv
+uv pip list --outdated 2>/dev/null || true
+
+# poetry
+poetry show --outdated 2>/dev/null || true
+```
+
+### Security Audit
+
+```bash
+# pip-audit (preferred)
+pip-audit 2>/dev/null || true
+
+# pip-audit with JSON output
+pip-audit --format json 2>/dev/null || true
+
+# safety (alternative)
+safety check 2>/dev/null || true
+```
+
+### Unused Detection
+
+Cross-reference manifest with source imports:
+
+```bash
+# List declared dependencies from pyproject.toml
+python3 -c "
+import tomllib, pathlib
+data = tomllib.loads(pathlib.Path('pyproject.toml').read_text())
+deps = data.get('project', {}).get('dependencies', [])
+for d in deps:
+    print(d.split('>=')[0].split('==')[0].split('<')[0].split('>')[0].split('~=')[0].strip())
+" 2>/dev/null || true
+```
+
+Then use Grep to search for `import pkg` or `from pkg import` across `.py` files.
+
+Known exceptions: pytest plugins, mypy/ruff extensions, ASGI/WSGI servers (uvicorn, gunicorn), and packages used only in configuration files.
+
+### Version Conflicts
+
+```bash
+# pip check for broken dependencies
+pip check 2>/dev/null || true
+```
+
+### License Listing
+
+```bash
+# pip-licenses
+pip-licenses 2>/dev/null || true
+
+# pip-licenses with format
+pip-licenses --format=json 2>/dev/null || true
+```
+
+---
+
+## Rust (cargo)
+
+### Outdated Packages
+
+```bash
+# Requires cargo-outdated
+cargo outdated 2>/dev/null || true
+
+# Alternative: check Cargo.toml against crates.io manually
+cargo search <crate_name> 2>/dev/null || true
+```
+
+### Security Audit
+
+```bash
+# Requires cargo-audit
+cargo audit 2>/dev/null || true
+
+# JSON output
+cargo audit --json 2>/dev/null || true
+```
+
+### Unused Detection
+
+```bash
+# Requires cargo-udeps (nightly)
+cargo +nightly udeps 2>/dev/null || true
+```
+
+If `cargo-udeps` is unavailable, cross-reference `Cargo.toml` `[dependencies]` with `use` statements in `src/**/*.rs`.
+
+### Version Conflicts
+
+```bash
+# Check dependency tree for duplicates
+cargo tree --duplicates 2>/dev/null || true
+```
+
+### License Listing
+
+```bash
+# Requires cargo-license
+cargo license 2>/dev/null || true
+
+# Alternative: cargo-deny
+cargo deny check licenses 2>/dev/null || true
+```
+
+---
+
+## Go
+
+### Outdated Packages
+
+```bash
+# List all dependencies with available updates
+go list -u -m all 2>/dev/null || true
+```
+
+### Security Audit
+
+```bash
+# Official Go vulnerability checker
+govulncheck ./... 2>/dev/null || true
+```
+
+### Unused Detection
+
+Go modules are imported explicitly. Check for modules in `go.mod` not imported in any `.go` file:
+
+```bash
+# List declared modules
+go list -m all 2>/dev/null | tail -n +2 || true
+
+# Tidy check (would remove unused, but don't run with -v to avoid modifications)
+# Instead, compare go.mod with actual imports via Grep
+```
+
+### Version Conflicts
+
+Go uses minimum version selection — conflicts are rare. Check for replace directives that may mask issues:
+
+```bash
+# Show replace directives
+grep -n "replace" go.mod 2>/dev/null || true
+
+# Verify module graph consistency
+go mod verify 2>/dev/null || true
+```
+
+### License Listing
+
+```bash
+# Requires go-licenses
+go-licenses csv ./... 2>/dev/null || true
+
+# Alternative: manual check via go.sum and module proxy
+```
+
+---
+
+## Error Handling
+
+When a tool is not installed:
+- Note it as **unavailable** in the report.
+- Skip that check and proceed to the next.
+- Suggest installation if the tool would provide significant value.
+- Never attempt to install tools — that changes system state.
+
+Common missing tools and alternatives:
+| Tool | Ecosystem | Alternative |
+|------|-----------|-------------|
+| `cargo-audit` | Rust | Check RustSec advisory DB manually |
+| `cargo-outdated` | Rust | `cargo search` per crate |
+| `pip-audit` | Python | `safety check` |
+| `govulncheck` | Go | Check Go vulnerability DB manually |
+| `license-checker` | Node.js | Read `license` field from each `node_modules/*/package.json` |

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 |