codeforge-dev 1.4.0 → 1.5.0

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/scripts/skill-suggester.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""Skill suggester hook for UserPromptSubmit and SubagentStart events.
+
+Detects which hook event called it via input JSON shape:
+- UserPromptSubmit: {"prompt": "..."} -> {"systemMessage": "..."}
+- SubagentStart:    {"subagent_type": "Plan", "prompt": "..."} -> {"additionalContext": "..."}
+
+Matches user prompts against skill keyword maps (phrases + terms) and suggests
+relevant skills. Outputs nothing when no skills match.
+"""
+
+import json
+import re
+import sys
+
+SKILLS = {
+    "fastapi": {
+        "phrases": [
+            "rest api",
+            "fastapi",
+            "fast api",
+            "pydantic model",
+            "sse streaming",
+            "server-sent event",
+            "dependency injection",
+            "asgi middleware",
+            "api endpoint",
+            "api route",
+        ],
+        "terms": ["fastapi", "pydantic", "uvicorn", "starlette"],
+    },
+    "sqlite": {
+        "phrases": [
+            "sqlite",
+            "wal mode",
+            "fts5",
+            "full-text search",
+            "better-sqlite3",
+            "cloudflare d1",
+            "json1 extension",
+        ],
+        "terms": ["aiosqlite"],
+    },
+    "claude-code-headless": {
+        "phrases": [
+            "headless mode",
+            "claude -p",
+            "stream-json",
+            "agent sdk",
+            "claude code headless",
+            "run claude in ci",
+            "claude in pipeline",
+        ],
+        "terms": [],
+    },
+    "pydantic-ai": {
+        "phrases": [
+            "pydantic ai",
+            "pydantic-ai",
+            "pydanticai",
+            "ai agent",
+            "runcontext",
+            "vercel ai adapter",
+            "model fallback",
+        ],
+        "terms": ["pydanticai"],
+    },
+    "testing": {
+        "phrases": [
+            "write tests",
+            "write a test",
+            "add tests",
+            "add a test",
+            "pytest fixture",
+            "vitest config",
+            "testing library",
+            "mock dependencies",
+            "test endpoint",
+            "test component",
+            "unit test",
+            "integration test",
+            "run tests",
+            "run the tests",
+        ],
+        "terms": ["pytest", "vitest"],
+    },
+    "docker-py": {
+        "phrases": [
+            "docker-py",
+            "docker py",
+            "docker sdk",
+            "docker engine api",
+            "docker from python",
+            "docker api",
+        ],
+        "terms": ["aiodocker"],
+    },
+    "svelte5": {
+        "phrases": [
+            "svelte component",
+            "sveltekit",
+            "svelte kit",
+            "svelte rune",
+            "svelte 5",
+            "svelte5",
+            "layercake",
+            "layer cake",
+            "svelte-dnd-action",
+            "svelte dnd",
+        ],
+        "terms": ["sveltekit", "svelte"],
+    },
+    "docker": {
+        "phrases": [
+            "dockerfile",
+            "docker compose",
+            "docker-compose",
+            "multi-stage build",
+            "health check",
+            "healthcheck",
+            "docker network",
+            "docker volume",
+            "docker image",
+        ],
+        "terms": ["dockerfile"],
+    },
+    "skill-building": {
+        "phrases": [
+            "build a skill",
+            "create a skill",
+            "write a skill",
+            "skill.md",
+            "skill instructions",
+            "skill authoring",
+            "design a skill",
+        ],
+        "terms": [],
+    },
+    "debugging": {
+        "phrases": [
+            "debug logs",
+            "check logs",
+            "find error",
+            "investigate failure",
+            "container logs",
+            "what went wrong",
+            "why did this crash",
+            "diagnose the issue",
+            "look at the logs",
+            "read the logs",
+            "analyze error",
+        ],
+        "terms": ["diagnose", "troubleshoot"],
+    },
+}
+
+# Pre-compile term patterns for whole-word matching
+_TERM_PATTERNS: dict[str, re.Pattern[str]] = {}
+for _skill, _cfg in SKILLS.items():
+    for _term in _cfg["terms"]:
+        if _term not in _TERM_PATTERNS:
+            _TERM_PATTERNS[_term] = re.compile(
+                r"\b" + re.escape(_term) + r"\b", re.IGNORECASE
+            )
+
+
+def match_skills(prompt: str) -> list[str]:
+    """Return sorted list of skill names matching the prompt."""
+    lowered = prompt.lower()
+    matched: list[str] = []
+
+    for skill, cfg in SKILLS.items():
+        # Check phrases (substring match on lowercased prompt)
+        if any(phrase in lowered for phrase in cfg["phrases"]):
+            matched.append(skill)
+            continue
+
+        # Check terms (whole-word regex match)
+        if any(_TERM_PATTERNS[term].search(prompt) for term in cfg["terms"]):
+            matched.append(skill)
+
+    matched.sort()
+    return matched
+
+
+def main() -> None:
+    raw = sys.stdin.read().strip()
+    if not raw:
+        return
+
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return
+
+    prompt = data.get("prompt", "")
+    if not prompt:
+        return
+
+    skills = match_skills(prompt)
+    if not skills:
+        return
+
+    skill_list = ", ".join(f'"{s}"' for s in skills)
+    is_subagent = "subagent_type" in data
+
+    if is_subagent:
+        output = {
+            "additionalContext": (
+                f"Available skills matching this planning task: {skill_list}. "
+                "These skills contain project-specific patterns, conventions, "
+                "and reference material. Consider their guidance when designing "
+                "the implementation approach."
+            )
+        }
+    else:
+        output = {
+            "systemMessage": (
+                f"<system-reminder>The user's prompt matches available skill(s): "
+                f"{skill_list}. Load the relevant skill(s) using the Skill tool "
+                f"before responding.</system-reminder>"
+            )
+        }
+
+    json.dump(output, sys.stdout)
+
+
+if __name__ == "__main__":
+    main()

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/scripts/syntax-validator.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""
+Data file syntax validator.
+
+Validates JSON, JSONC, YAML, and TOML files after editing.
+Uses Python stdlib only (plus PyYAML if available).
+
+Reads tool input from stdin, validates syntax, reports errors.
+Non-blocking: always exits 0.
+"""
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+EXTENSIONS = {".json", ".jsonc", ".yaml", ".yml", ".toml"}
+
+
+def strip_jsonc_comments(text: str) -> str:
+    """Remove // and /* */ comments from JSONC text."""
+    # Remove single-line comments (not inside strings)
+    text = re.sub(r"(?<!:)//.*$", "", text, flags=re.MULTILINE)
+    # Remove multi-line comments
+    text = re.sub(r"/\*.*?\*/", "", text, flags=re.DOTALL)
+    return text
+
+
+def validate_json(file_path: str, is_jsonc: bool) -> str:
+    """Validate JSON/JSONC syntax.
+
+    Returns:
+        Error message string, or empty string if valid.
+    """
+    with open(file_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    if is_jsonc:
+        content = strip_jsonc_comments(content)
+
+    try:
+        json.loads(content)
+        return ""
+    except json.JSONDecodeError as e:
+        return f"[Syntax] JSON error at line {e.lineno}, col {e.colno}: {e.msg}"
+
+
+def validate_yaml(file_path: str) -> str:
+    """Validate YAML syntax.
+
+    Returns:
+        Error message string, or empty string if valid.
+    """
+    try:
+        import yaml
+    except ImportError:
+        return ""  # PyYAML not available, skip
+
+    try:
+        with open(file_path, "r", encoding="utf-8") as f:
+            yaml.safe_load(f)
+        return ""
+    except yaml.YAMLError as e:
+        if hasattr(e, "problem_mark"):
+            mark = e.problem_mark
+            return f"[Syntax] YAML error at line {mark.line + 1}, col {mark.column + 1}: {e.problem}"
+        return f"[Syntax] YAML error: {e}"
+
+
+def validate_toml(file_path: str) -> str:
+    """Validate TOML syntax.
+
+    Returns:
+        Error message string, or empty string if valid.
+    """
+    try:
+        import tomllib
+    except ImportError:
+        return ""  # Python < 3.11, skip
+
+    try:
+        with open(file_path, "rb") as f:
+            tomllib.load(f)
+        return ""
+    except tomllib.TOMLDecodeError as e:
+        return f"[Syntax] TOML error: {e}"
+
+
+def validate(file_path: str) -> str:
+    """Validate file syntax based on extension.
+
+    Returns:
+        Error message string, or empty string if valid.
+    """
+    ext = Path(file_path).suffix.lower()
+
+    if ext == ".jsonc":
+        return validate_json(file_path, is_jsonc=True)
+    elif ext == ".json":
+        return validate_json(file_path, is_jsonc=False)
+    elif ext in {".yaml", ".yml"}:
+        return validate_yaml(file_path)
+    elif ext == ".toml":
+        return validate_toml(file_path)
+
+    return ""
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+        tool_input = input_data.get("tool_input", {})
+        file_path = tool_input.get("file_path", "")
+
+        if not file_path:
+            sys.exit(0)
+
+        ext = Path(file_path).suffix.lower()
+        if ext not in EXTENSIONS:
+            sys.exit(0)
+
+        if not os.path.isfile(file_path):
+            sys.exit(0)
+
+        message = validate(file_path)
+
+        if message:
+            print(json.dumps({"additionalContext": message}))
+
+        sys.exit(0)
+
+    except json.JSONDecodeError:
+        sys.exit(0)
+    except Exception as e:
+        print(f"Hook error: {e}", file=sys.stderr)
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,165 @@
+---
+name: debugging
+description: >-
+  This skill should be used when the user asks to "debug logs", "check logs",
+  "find error in logs", "read docker logs", "investigate failure",
+  "check container logs", "analyze error output", "find what went wrong",
+  "why did this crash", "check what happened", "diagnose the issue",
+  "look at the logs", or discusses log analysis, container debugging,
+  error investigation, crash diagnosis, or service failure troubleshooting.
+version: 0.1.0
+---
+
+# Debugging & Log Analysis
+
+## Mental Model
+
+Logs are **forensic evidence**. Debugging is a scientific method: observe symptoms, form hypotheses, gather evidence, test hypotheses, converge on root cause.
+
+Every running system produces a trail of structured and unstructured log entries. Errors rarely happen in isolation — they cascade. The first error in a sequence is usually the root cause; everything after it is a consequence. Your job is to find that first domino.
+
+**Key principles:**
+- **Broad scan, then narrow focus.** Don't assume you know where the problem is. Survey all available log sources first, then zoom in on anomalies.
+- **Chronology is king.** Timestamps tell you the order of events. The order of events tells you causality.
+- **Absence of evidence is evidence.** If a service has no error logs, that's useful information — the problem is elsewhere.
+- **Correlation across sources.** A single log source gives you symptoms. Multiple correlated sources give you root causes.
+
+---
+
+## Log Discovery by Environment
+
+| Environment | Primary Sources | Key Commands |
+|---|---|---|
+| **Docker** | Container stdout/stderr, Docker events | `docker logs`, `docker ps -a`, `docker inspect`, `docker events` |
+| **Docker Compose** | Aggregated service logs | `docker compose logs`, `docker compose ps` |
+| **Linux systemd** | Journal, syslog | `journalctl -u <service>`, `journalctl -k` |
+| **Python / FastAPI** | Uvicorn stderr, application loggers | Check `logging.conf`, `UVICORN_LOG_LEVEL`, stdout |
+| **Node.js** | Console output, PM2 logs | `~/.pm2/logs/`, application `logs/` directory |
+| **Nginx** | Access & error logs | `/var/log/nginx/error.log`, `/var/log/nginx/access.log` |
+| **PostgreSQL** | Server log | `/var/log/postgresql/`, `pg_log/` |
+| **Redis** | Server log | `/var/log/redis/`, `redis-server.log` |
+
+---
+
+## Common Log Locations Quick Reference
+
+**System:**
+- `/var/log/syslog` or `/var/log/messages` — General system log
+- `/var/log/kern.log` — Kernel messages (OOM killer lives here)
+- `/var/log/auth.log` — Authentication events
+- `journalctl` — systemd journal (binary, query with flags)
+
+**Docker:**
+- Container logs via `docker logs <name>` (stored at `/var/lib/docker/containers/<id>/<id>-json.log`)
+- Docker daemon: `/var/log/docker.log` or `journalctl -u docker`
+
+**Applications:**
+- Project `./logs/` directory
+- Framework defaults (see reference files for exhaustive list)
+- `/tmp/*.log` for transient application logs
+
+---
+
+## Docker Log Analysis
+
+Docker captures everything a container writes to stdout and stderr. This is your primary source in containerized environments.
+
+**Essential commands:**
+
+```bash
+# Overview: what's running, what's dead
+docker ps -a --format "table {{.Names}}\t{{.Status}}\t{{.Image}}"
+
+# Recent logs with timestamps
+docker logs --tail 200 --timestamps <container>
+
+# Time-windowed logs
+docker logs --since "30m" <container>
+
+# All Compose services, interleaved chronologically
+docker compose logs --tail 100 --timestamps
+
+# Container health and exit info
+docker inspect --format '{{json .State}}' <container> | python3 -m json.tool
+```
+
+**Exit code interpretation:**
+- `0` — Clean exit
+- `1` — Generic application error
+- `2` — Misuse of shell command
+- `126` — Cannot execute (permission denied on entrypoint)
+- `127` — Command not found (bad entrypoint/CMD)
+- `137` — SIGKILL (OOM killer or forced kill)
+- `143` — SIGTERM (graceful shutdown timeout)
+- `255` — Exit status out of range
+
+---
+
+## Log Format Parsing
+
+**JSON logs** (common with structured logging frameworks):
+```bash
+# Parse JSON logs with jq
+docker logs <container> 2>&1 | python3 -c "
+import sys, json
+for line in sys.stdin:
+    try:
+        obj = json.loads(line)
+        level = obj.get('level', obj.get('levelname', '?'))
+        msg = obj.get('message', obj.get('msg', line.strip()))
+        print(f'{level}: {msg}')
+    except json.JSONDecodeError:
+        print(line.strip())
+"
+```
+
+**Python tracebacks** — Multi-line. Look for `Traceback (most recent call last):` as the start marker. The actual error is the **last line** of the traceback block.
+
+**Stack traces** (Java, Go, Node) — Look for `at `, `goroutine`, or `Error:` as anchors. The top frame is where the error was thrown; the bottom frame is the entry point.
+
+---
+
+## Error Pattern Recognition
+
+**Connection errors:**
+- `ECONNREFUSED` / `Connection refused` — Target service isn't running or isn't listening on expected port
+- `ETIMEDOUT` / `Connection timed out` — Network unreachable or firewall blocking
+- `ENOTFOUND` / `Name resolution failed` — DNS failure, usually wrong hostname in config
+
+**Resource exhaustion:**
+- `OOMKilled` / `Killed` / exit code 137 — Container exceeded memory limit
+- `No space left on device` — Disk full (check `df -h`, Docker image/volume storage)
+- `Too many open files` — File descriptor limit hit
+
+**Permission errors:**
+- `EACCES` / `Permission denied` — File/directory ownership mismatch
+- `EPERM` / `Operation not permitted` — Capability or security context restriction
+- Docker socket permission — User not in `docker` group
+
+**Application errors:**
+- `Unhandled promise rejection` / `UnhandledPromiseRejection` — Node.js async error
+- `Traceback (most recent call last)` — Python unhandled exception
+- `panic:` — Go runtime panic
+
+---
+
+## Ambiguity Policy
+
+When the user's request is ambiguous, apply these defaults:
+
+| Ambiguity | Default |
+|---|---|
+| **Scope not specified** | Check ALL available sources (Docker first, then files, then system) |
+| **Timeframe not specified** | Last 1 hour |
+| **Severity not specified** | Report ERROR and CRITICAL first, then WARNING if relevant |
+| **Service not specified** | Scan all running containers and accessible log files |
+| **"It's not working"** | Broad scan for any error-level entries in the last hour |
+
+---
+
+## Reference Files
+
+| File | Contents |
+|---|---|
+| [Log Locations](references/log-locations.md) | Exhaustive reference of log file paths organized by system, Docker, Python, Node.js, databases, and web servers |
+| [Error Patterns](references/error-patterns.md) | Error pattern catalog with symptoms, diagnosis commands, and resolutions for connection, resource, permission, application, and Docker-specific errors |