codeforge-dev 1.4.0 → 1.5.0

package/.devcontainer/plugins/devs-marketplace/plugins/auto-formatter/scripts/format-on-stop.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""
+Unified batch formatter — runs as a Stop hook.
+
+Reads file paths collected by collect-edited-files.py during the
+conversation turn, deduplicates them, and formats each based on
+extension:
+  .py / .pyi       → Black
+  .go              → gofmt
+  .js/.jsx/.ts/.tsx/.mjs/.cjs/.mts/.cts/.css → Biome (safe mode)
+
+Always cleans up the temp file. Always exits 0.
+"""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+# Formatter dispatch by extension
+PYTHON_EXTS = {".py", ".pyi"}
+GO_EXTS = {".go"}
+BIOME_EXTS = {
+    ".js",
+    ".jsx",
+    ".ts",
+    ".tsx",
+    ".mjs",
+    ".cjs",
+    ".mts",
+    ".cts",
+    ".css",
+}
+
+BLACK_PATH = "/usr/local/py-utils/bin/black"
+GOFMT_PATH = "/usr/local/go/bin/gofmt"
+
+
+def find_tool_upward(file_path: str, tool_name: str) -> str | None:
+    """Walk up from file directory looking for node_modules/.bin/<tool>."""
+    current = Path(file_path).parent
+    for _ in range(20):
+        candidate = current / "node_modules" / ".bin" / tool_name
+        if candidate.is_file():
+            return str(candidate)
+        parent = current.parent
+        if parent == current:
+            break
+        current = parent
+    return None
+
+
+def find_global_tool(tool_name: str) -> str | None:
+    """Check if tool is available globally."""
+    try:
+        result = subprocess.run(
+            ["which", tool_name],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+    except Exception:
+        pass
+    return None
+
+
+def find_biome(file_path: str) -> str | None:
+    """Find biome binary: project-local first, then global."""
+    local = find_tool_upward(file_path, "biome")
+    if local:
+        return local
+    return find_global_tool("biome")
+
+
+def format_python(file_path: str) -> None:
+    """Format with Black (quiet mode)."""
+    if not os.path.exists(BLACK_PATH):
+        return
+    try:
+        subprocess.run(
+            [BLACK_PATH, "--quiet", file_path],
+            capture_output=True,
+            timeout=10,
+        )
+    except (subprocess.TimeoutExpired, OSError):
+        pass
+
+
+def format_go(file_path: str) -> None:
+    """Format with gofmt."""
+    if not os.path.exists(GOFMT_PATH):
+        return
+    try:
+        subprocess.run(
+            [GOFMT_PATH, "-w", file_path],
+            capture_output=True,
+            timeout=10,
+        )
+    except (subprocess.TimeoutExpired, OSError):
+        pass
+
+
+def format_biome(file_path: str) -> None:
+    """Format with Biome in safe mode (no --unsafe)."""
+    biome = find_biome(file_path)
+    if not biome:
+        return
+    try:
+        subprocess.run(
+            [biome, "check", "--write", file_path],
+            capture_output=True,
+            timeout=12,
+        )
+    except (subprocess.TimeoutExpired, OSError):
+        pass
+
+
+def format_file(file_path: str) -> None:
+    """Dispatch to the correct formatter based on extension."""
+    ext = Path(file_path).suffix.lower()
+    if ext in PYTHON_EXTS:
+        format_python(file_path)
+    elif ext in GO_EXTS:
+        format_go(file_path)
+    elif ext in BIOME_EXTS:
+        format_biome(file_path)
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        sys.exit(0)
+
+    # Prevent infinite loops if Stop hook triggers another stop
+    if input_data.get("stop_hook_active"):
+        sys.exit(0)
+
+    session_id = input_data.get("session_id", "")
+    if not session_id:
+        sys.exit(0)
+
+    tmp_path = f"/tmp/claude-edited-files-{session_id}"
+
+    try:
+        with open(tmp_path) as f:
+            raw_paths = f.read().splitlines()
+    except FileNotFoundError:
+        sys.exit(0)
+    except OSError:
+        sys.exit(0)
+    finally:
+        # Always clean up the temp file
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+
+    # Deduplicate while preserving order, filter to existing files
+    seen: set[str] = set()
+    paths: list[str] = []
+    for p in raw_paths:
+        p = p.strip()
+        if p and p not in seen and os.path.isfile(p):
+            seen.add(p)
+            paths.append(p)
+
+    for path in paths:
+        format_file(path)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.devcontainer/plugins/devs-marketplace/plugins/auto-linter/hooks/hooks.json

@@ -8,7 +8,8 @@
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/lint-file.py",
-            "timeout": 60
+            "timeout": 15,
+            "async": true
           }
         ]
       }

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/.claude-plugin/commands/debug.md

@@ -0,0 +1,86 @@
+---
+description: Investigate logs and diagnose issues using the debug-logs agent
+argument-hint: [error description, container/service name, or timeframe]
+allowed-tools: Bash, Read, Glob, Grep, Task
+---
+
+# /debug - Log Investigation & Issue Diagnosis
+
+Investigate application, container, and system logs to diagnose failures and errors.
+
+## Input
+
+`$ARGUMENTS` - Optional scope hint. Can be:
+- An error message or description (e.g., "connection refused on port 5432")
+- A container or service name (e.g., "web", "postgres")
+- A timeframe (e.g., "last 30 minutes", "since deployment")
+- A combination (e.g., "OOM errors in worker container since noon")
+- Empty (triggers a broad scan of all available log sources)
+
+## Process
+
+### Step 1: Load Domain Knowledge
+
+**CRITICAL:** Before any log analysis, invoke the `debugging` skill to load log analysis domain knowledge. This ensures you have the full reference material for log locations, error patterns, and diagnosis procedures.
+
+### Step 2: Parse Scope
+
+Analyze `$ARGUMENTS` to determine:
+- **Target service/container**: Specific container name, service name, or "all"
+- **Error type**: What kind of error to look for, or "any"
+- **Timeframe**: How far back to look (default: 1 hour)
+
+If arguments are empty, set scope to: all sources, any errors, last 1 hour.
+
+### Step 3: Delegate to Debug Agent
+
+**CRITICAL:** You MUST use the `debug-logs` agent (via the Task tool) for all log analysis work. Do NOT read logs directly — delegate to the agent.
+
+Construct a clear task description for the agent that includes:
+- What to investigate (the parsed scope from Step 2)
+- Any specific error messages or patterns to search for
+- The timeframe to focus on
+- What the user reported as the symptom
+
+Example delegation:
+```
+Investigate logs for the "web" container. The user reports "connection refused" errors.
+Focus on the last 1 hour. Check the web container logs, any dependent service containers
+(database, redis, etc.), and correlate timestamps to find the root cause.
+```
+
+### Step 4: Present Findings
+
+When the agent returns its findings, present them to the user in this format:
+
+**Summary** - One-sentence root cause assessment.
+
+**What Was Checked** - List of all log sources examined.
+
+**Errors Found** - Each error with severity, timestamp, source, and context. Highlight the root cause error distinctly from downstream effects.
+
+**Timeline** - Chronological sequence of events if multiple errors were found.
+
+**Recommended Actions** - Ordered steps to resolve the issue, with specific commands or code changes.
+
+### Step 5: Follow Up (if inconclusive)
+
+If the agent's findings are inconclusive:
+1. Identify what additional information would help
+2. Re-invoke the agent with a narrower or different scope
+3. Consider checking different log sources or expanding the timeframe
+4. Report partial findings to the user and suggest manual investigation steps
+
+## Examples
+
+**Broad scan (no arguments):**
+> User: `/debug`
+> Action: Delegate to agent with "Perform a broad scan of all available log sources from the last hour. List all containers, find all log files, check system logs. Report any errors, warnings, or anomalies."
+
+**Specific container:**
+> User: `/debug postgres container keeps restarting`
+> Action: Delegate to agent with "Investigate the postgres container. It is reportedly restarting repeatedly. Check container exit codes, restart count, logs before each crash, memory usage, and health check status."
+
+**Error investigation:**
+> User: `/debug 502 Bad Gateway`
+> Action: Delegate to agent with "Investigate 502 Bad Gateway errors. Check the reverse proxy / web server logs (nginx, caddy, etc.) for upstream connection failures, then check the upstream application container logs for crashes or errors that would cause it to be unavailable."

package/.devcontainer/plugins/devs-marketplace/plugins/{codedirective-skills → code-directive}/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
-  "name": "codedirective-skills",
+  "name": "code-directive",
   "description": "Coding standards and skills for the CodeDirective project",
   "version": "1.0.0",
   "author": {

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/debug-logs.md

@@ -0,0 +1,149 @@
+---
+name: debug-logs
+description: >-
+  Read-only agent that finds and analyzes log files across Docker containers,
+  application frameworks, and system services to identify errors, crashes,
+  and performance issues. Reports structured findings with root cause assessment.
+tools: Bash, Read, Glob, Grep
+model: sonnet
+color: red
+---
+
+# Debug Logs Agent
+
+You are a **read-only log analysis specialist**. Your purpose is to find, read, and analyze log files to diagnose issues. You help developers understand what went wrong by examining Docker container logs, application log files, and system logs.
+
+## Critical Constraints
+
+- **NEVER** modify any file, configuration, or system state.
+- **NEVER** restart services, containers, or processes.
+- **NEVER** install packages or change permissions.
+- **NEVER** write files, create directories, or alter environment variables.
+- You are strictly **read-only**. Your only actions are reading logs, searching content, and running diagnostic commands that produce output without side effects.
+
+## Log Discovery Strategy
+
+When investigating an issue, follow this priority order. Cast a wide net first, then narrow based on findings.
+
+### Priority 1: Docker Container Logs
+
+Docker is the most common runtime environment. Start here unless the user specifies otherwise.
+
+```bash
+# List all containers (including stopped ones)
+docker ps -a --format "table {{.Names}}\t{{.Status}}\t{{.Image}}\t{{.Ports}}"
+
+# Get recent logs from a specific container (last 200 lines)
+docker logs --tail 200 <container_name>
+
+# Get logs with timestamps for chronology
+docker logs --tail 200 --timestamps <container_name>
+
+# Get logs from a specific time window
+docker logs --since "1h" <container_name>
+docker logs --since "2025-01-15T10:00:00" <container_name>
+
+# Aggregate logs from all Compose services
+docker compose logs --tail 100
+
+# Inspect container for exit codes, state, health checks
+docker inspect --format '{{.State.Status}} exit:{{.State.ExitCode}} oom:{{.State.OOMKilled}}' <container_name>
+
+# Check recent Docker events
+docker events --since "1h" --until "now" --format '{{.Time}} {{.Type}} {{.Action}} {{.Actor.Attributes.name}}'
+```
+
+If a container has exited, always check its exit code. Key exit codes:
+- **0**: Clean shutdown
+- **1**: Application error
+- **137** (128+9): Killed by SIGKILL (usually OOM or `docker kill`)
+- **143** (128+15): Killed by SIGTERM (graceful stop timed out or `docker stop`)
+- **126**: Permission denied on entrypoint
+- **127**: Entrypoint command not found
+
+### Priority 2: Application Log Files
+
+Search for log files in common locations:
+
+```bash
+# Project-local logs
+# Use Glob: ./**/*.log, ./logs/**, ./log/**
+
+# Framework-specific paths
+# Python/FastAPI/Uvicorn: ./logs/, /tmp/*.log
+# Node.js/Express: ./logs/, ./combined.log, ./error.log
+# PM2: ~/.pm2/logs/
+
+# System-installed application logs
+# /var/log/<app_name>/
+```
+
+Use `Glob` to discover log files, then `Grep` to search for error indicators before reading full files. For large logs, always filter first:
+
+```bash
+# Search for error patterns across discovered log files
+# Use Grep with patterns: ERROR, FATAL, Traceback, panic, CRITICAL, Exception
+```
+
+### Priority 3: System Logs
+
+When Docker and application logs are insufficient:
+
+```bash
+# Recent system journal entries
+journalctl --no-pager -n 100 --since "1 hour ago"
+
+# Kernel messages (OOM killer, hardware errors)
+journalctl --no-pager -n 50 -k --since "1 hour ago"
+
+# Service-specific journal
+journalctl --no-pager -n 100 -u <service_name> --since "1 hour ago"
+
+# Disk space (often the hidden cause)
+df -h
+
+# Memory pressure
+free -h
+```
+
+## Analysis Procedure
+
+1. **Collect Sources** - Identify all available log sources. List what exists before diving deep.
+2. **Scan for Error Indicators** - Use Grep across all sources for: `ERROR`, `FATAL`, `CRITICAL`, `Traceback`, `panic`, `segfault`, `OOMKilled`, `exit code`, `refused`, `timeout`, `denied`.
+3. **Establish Chronology** - Sort errors by timestamp. The first error in a cascade is usually the root cause; subsequent errors are often consequences.
+4. **Correlate Across Sources** - If Service A failed at 10:02 and Service B started erroring at 10:03, Service A is likely the root cause.
+5. **Assess Root Cause** - Distinguish between the triggering event and its downstream effects. Look for the earliest anomaly.
+
+## Behavioral Rules
+
+- **No arguments provided**: Perform a broad scan. List all containers, find all log files, check system logs. Report everything found.
+- **Service/container name provided**: Focus on that service. Check its container logs, any related log files, and its dependencies.
+- **Error description provided**: Search all sources for that specific error pattern. Report where it appears, when, and what preceded it.
+- **Timeframe provided**: Limit all queries to that window.
+- **Always report what was checked**, even if nothing was found. Negative results ("No errors in nginx logs for the past hour") are valuable.
+- For large log files (>1000 lines), use Grep to identify relevant sections before reading. Never dump entire large logs.
+
+## Output Format
+
+Structure your findings as follows:
+
+### Sources Examined
+List every log source you checked, with line counts or time ranges.
+
+### Errors Found
+For each error, provide:
+- **Severity**: CRITICAL / ERROR / WARNING
+- **Timestamp**: When it occurred
+- **Source**: Which log file or container
+- **Message**: The actual error text (quoted)
+- **Context**: 2-3 lines before/after the error
+- **Likely Cause**: Your assessment of what triggered this specific error
+
+### Timeline
+Chronological sequence of events leading to the issue. Include the first normal log entry, the first anomaly, and the cascade of failures.
+
+### Root Cause Assessment
+Your best assessment of the underlying cause, based on the evidence. State your confidence level (high/medium/low) and what additional information would increase confidence.
+
+### Recommended Actions
+Ordered list of steps the developer should take to resolve the issue. Be specific — name the exact service, configuration, or code path involved.

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/hooks/hooks.json

@@ -0,0 +1,46 @@
+{
+  "description": "Code quality hooks and skill suggestions for the CodeDirective project",
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/skill-suggester.py",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "Plan",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/skill-suggester.py",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/syntax-validator.py",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/collect-edited-files.py",
+            "timeout": 3
+          }
+        ]
+      }
+    ]
+  }
+}

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/scripts/collect-edited-files.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""
+Collect edited file paths for batch formatting at Stop.
+
+Lightweight PostToolUse hook that appends the edited file path
+to a session-scoped temp file. The auto-formatter Stop hook
+reads this file to know which files need formatting.
+
+Non-blocking: always exits 0. Runs in <10ms.
+"""
+
+import json
+import os
+import sys
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        sys.exit(0)
+
+    session_id = input_data.get("session_id", "")
+    tool_input = input_data.get("tool_input", {})
+    file_path = tool_input.get("file_path", "")
+
+    if not file_path or not session_id:
+        sys.exit(0)
+
+    if not os.path.isfile(file_path):
+        sys.exit(0)
+
+    tmp_path = f"/tmp/claude-edited-files-{session_id}"
+    try:
+        with open(tmp_path, "a") as f:
+            f.write(file_path + "\n")
+    except OSError:
+        pass  # non-critical, don't block Claude
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()