wicked-garden 12.27.0

package/scripts/_wicked_testing_probe.py

@@ -0,0 +1,277 @@
+#!/usr/bin/env python3
+"""
+_wicked_testing_probe.py — wicked-testing version probe.
+
+Checks that `wicked-testing` (npm) is installed and satisfies the semver
+range pinned in .claude-plugin/plugin.json:wicked_testing_version.
+
+Public API:
+    probe(session_state) -> ProbeResult
+    read_pin_from_plugin_json(plugin_json_path: str) -> str
+    is_version_in_range(installed: str, pin: str) -> bool
+
+Stdlib-only: no third-party imports (packaging, semver, etc.).
+
+Escape hatch: WG_SKIP_WICKED_TESTING_CHECK=1 bypasses subprocess entirely and
+returns status "ok". Documented in CONTRIBUTING.md. Do NOT use in production.
+
+CH-02 hardening: the exception path in probe() logs actionable detail —
+subprocess stderr, the exact command that was run, and timeout context — not
+just the bare exception string. crew_command_gate() treats a missing probe key
+as a failure (fail-closed), closing the fail-open gap at the crew layer.
+"""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+try:
+    from typing import TypedDict
+
+    class ProbeResult(TypedDict):
+        status: str          # "ok" | "missing" | "out-of-range" | "error"
+        version: Optional[str]
+        pin: str
+        error: Optional[str]
+
+except ImportError:
+    # Python 3.7 fallback — TypedDict not available as class syntax
+    ProbeResult = dict  # type: ignore
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_PLUGIN_ROOT = Path(os.environ.get("CLAUDE_PLUGIN_ROOT", Path(__file__).resolve().parents[1]))
+_PLUGIN_JSON_PATH = str(_PLUGIN_ROOT / ".claude-plugin" / "plugin.json")
+
+# Subprocess command for the probe. Factored out so tests can assert it.
+_PROBE_CMD = ["npx", "wicked-testing", "--version"]
+_PROBE_TIMEOUT_S = 3
+
+
+# ---------------------------------------------------------------------------
+# Semver-lite caret-range parser (stdlib only, no packaging import)
+# ---------------------------------------------------------------------------
+
+def is_version_in_range(installed: str, pin: str) -> bool:
+    """Evaluate a caret semver range.
+
+    Supports:
+      - "*" wildcard: accepts any non-empty installed version string.
+      - Caret range "^X.Y.Z":
+        - X > 0:  >=X.Y.Z and <(X+1).0.0
+        - X == 0: >=0.Y.Z and <0.(Y+1).0
+
+    Prerelease tags (e.g. "0.1.1-beta.1") are rejected for caret ranges —
+    strip the prerelease suffix from installed before the numeric comparison.
+
+    Returns False for any malformed input.
+    """
+    if pin == "*":
+        return bool(installed)
+
+    if not pin.startswith("^"):
+        return False
+
+    pin_bare = pin[1:]  # strip "^"
+
+    def _parse(v: str):
+        """Parse "X.Y.Z" (possibly with prerelease tag) → (major, minor, patch) or None."""
+        # Strip prerelease tag — "0.1.1-beta.1" → "0.1.1"
+        numeric_part = v.split("-")[0]
+        parts = numeric_part.split(".")
+        if len(parts) != 3:
+            return None
+        try:
+            return tuple(int(p) for p in parts)
+        except ValueError:
+            return None
+
+    inst_tuple = _parse(installed)
+    pin_tuple = _parse(pin_bare)
+
+    if inst_tuple is None or pin_tuple is None:
+        return False
+
+    inst_major, inst_minor, inst_patch = inst_tuple
+    pin_major, pin_minor, pin_patch = pin_tuple
+
+    # Reject prerelease tags (original installed string has "-")
+    if "-" in installed.split("+")[0]:  # ignore build metadata "+" but reject "-"
+        return False
+
+    # Must be >= pin
+    if inst_tuple < pin_tuple:
+        return False
+
+    # Upper bound: <(X+1).0.0 when X>0, or <0.(Y+1).0 when X==0
+    if pin_major > 0:
+        if inst_major >= pin_major + 1:
+            return False
+    else:
+        # pin_major == 0 — locked to minor
+        if inst_major != 0:
+            return False
+        if inst_minor >= pin_minor + 1:
+            return False
+
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Read pin from plugin.json
+# ---------------------------------------------------------------------------
+
+def read_pin_from_plugin_json(plugin_json_path: str) -> str:
+    """Read the wicked_testing_version field from plugin.json.
+
+    Raises ValueError with an actionable message when:
+    - The file does not exist or cannot be read.
+    - The JSON is malformed.
+    - The wicked_testing_version field is absent.
+    - The field value is not a string.
+    """
+    path = Path(plugin_json_path)
+    if not path.exists():
+        raise ValueError(
+            f"plugin.json not found at {plugin_json_path}. "
+            "Ensure CLAUDE_PLUGIN_ROOT is set correctly."
+        )
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as e:
+        raise ValueError(f"plugin.json unreadable ({plugin_json_path}): {e}") from e
+
+    value = data.get("wicked_testing_version")
+    if value is None:
+        raise ValueError(
+            f"plugin.json missing wicked_testing_version field ({plugin_json_path}). "
+            "Add: \"wicked_testing_version\": \"^0.2.0\""
+        )
+    if not isinstance(value, str):
+        raise ValueError(
+            f"plugin.json wicked_testing_version must be a string, "
+            f"got {type(value).__name__} ({plugin_json_path})"
+        )
+    return value
+
+
+# ---------------------------------------------------------------------------
+# Main probe
+# ---------------------------------------------------------------------------
+
+def probe(session_state=None) -> "ProbeResult":
+    """Run the wicked-testing availability probe.
+
+    1. Check WG_SKIP_WICKED_TESTING_CHECK escape hatch.
+    2. Read version pin from plugin.json.
+    3. Run `npx wicked-testing --version` with a 3s timeout.
+    4. Compare version string against the caret pin.
+
+    Returns a ProbeResult dict with keys:
+        status:  "ok" | "missing" | "out-of-range" | "error"
+        version: installed version string or None
+        pin:     required range string (or "skipped")
+        error:   error detail or None
+
+    CH-02 hardening: exception paths log subprocess stderr + command + timeout
+    context. The caller (_probe_wicked_testing in bootstrap.py) catches any
+    exceptions that escape this function and fails-open. crew_command_gate()
+    treats an absent probe key as a failure — fail-closed at the crew layer.
+    """
+    # 1. Escape hatch — for CI / offline dev without npm access.
+    if os.environ.get("WG_SKIP_WICKED_TESTING_CHECK", "").strip() == "1":
+        print(
+            "[wicked-garden] WG_SKIP_WICKED_TESTING_CHECK is set — "
+            "wicked-testing version check bypassed (offline dev mode). "
+            "Do not use in production.",
+            file=sys.stderr,
+        )
+        return {"status": "ok", "version": "skipped", "pin": "skipped", "error": None}
+
+    # 2. Read the version pin.
+    try:
+        pin = read_pin_from_plugin_json(_PLUGIN_JSON_PATH)
+    except ValueError as exc:
+        return {
+            "status": "error",
+            "version": None,
+            "pin": "unknown",
+            "error": str(exc),
+        }
+
+    # 3. Run the probe subprocess.
+    try:
+        result = subprocess.run(
+            _PROBE_CMD,
+            capture_output=True,
+            text=True,
+            timeout=_PROBE_TIMEOUT_S,
+        )
+    except FileNotFoundError:
+        # npx binary not found — Node.js is not installed.
+        return {
+            "status": "missing",
+            "version": None,
+            "pin": pin,
+            "error": "npx not found — install Node.js",
+        }
+    except subprocess.TimeoutExpired as exc:
+        # CH-02 hardening: include command + timeout context in the log line.
+        cmd_str = " ".join(_PROBE_CMD)
+        stderr_excerpt = ""
+        if exc.stderr:
+            raw = exc.stderr if isinstance(exc.stderr, str) else exc.stderr.decode("utf-8", errors="replace")
+            stderr_excerpt = raw.strip()[:200]
+        print(
+            f"[wicked-garden] wicked-testing probe timeout: "
+            f"command={cmd_str!r} timeout={_PROBE_TIMEOUT_S}s "
+            f"stderr={stderr_excerpt!r}",
+            file=sys.stderr,
+        )
+        return {
+            "status": "error",
+            "version": None,
+            "pin": pin,
+            "error": f"probe timeout ({_PROBE_TIMEOUT_S}s)",
+        }
+    except Exception as exc:
+        # CH-02 hardening: include command context in the actionable log line.
+        cmd_str = " ".join(_PROBE_CMD)
+        print(
+            f"[wicked-garden] wicked-testing probe exception: "
+            f"command={cmd_str!r} error={exc!r}",
+            file=sys.stderr,
+        )
+        return {
+            "status": "error",
+            "version": None,
+            "pin": pin,
+            "error": str(exc),
+        }
+
+    # 4. Non-zero exit → wicked-testing not installed (or broken install).
+    if result.returncode != 0:
+        stderr_excerpt = result.stderr.strip()[:200] if result.stderr else "non-zero exit"
+        return {
+            "status": "missing",
+            "version": None,
+            "pin": pin,
+            "error": stderr_excerpt or "non-zero exit",
+        }
+
+    # 5. Parse and validate the version string.
+    version = result.stdout.strip().lstrip("v")
+    if not is_version_in_range(version, pin):
+        return {
+            "status": "out-of-range",
+            "version": version,
+            "pin": pin,
+            "error": None,
+        }
+
+    return {"status": "ok", "version": version, "pin": pin, "error": None}

package/scripts/agentic/analyze_agents.py

@@ -0,0 +1,391 @@
+#!/usr/bin/env python3
+"""
+Agent topology analysis for agentic codebases.
+
+Extracts agent definitions, classifies roles, maps communication patterns,
+and identifies structural characteristics like nesting depth and tool sharing.
+
+Usage:
+    python3 analyze_agents.py --path DIR [--framework NAME]
+"""
+
+import ast
+import json
+import os
+import re
+import sys
+import time
+from pathlib import Path
+
+EXCLUDE_DIRS = {
+    "node_modules", "venv", ".venv", "__pycache__", "dist", "build",
+    ".git", ".tox", ".mypy_cache", ".pytest_cache",
+}
+
+ROLE_KEYWORDS = {
+    "research": ["search", "research", "gather", "find", "retrieve", "scrape"],
+    "analysis": ["analyze", "evaluate", "assess", "review", "score", "classify"],
+    "coordination": ["supervisor", "manager", "orchestrat", "coordinate", "router", "planner"],
+    "execution": ["execute", "perform", "run", "worker", "do", "process"],
+    "safety": ["safety", "validate", "check", "guard", "moderate", "filter"],
+    "synthesis": ["synthesize", "combine", "summarize", "aggregate", "merge", "report"],
+    "creation": ["write", "create", "generate", "compose", "draft", "author"],
+}
+
+
+def find_python_files(root: str, max_files: int = 500) -> list:
+    files = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in EXCLUDE_DIRS]
+        for f in filenames:
+            if f.endswith(".py"):
+                files.append(os.path.join(dirpath, f))
+                if len(files) >= max_files:
+                    return files
+    return files
+
+
+def extract_agents_generic(filepath: str) -> list:
+    """Extract agent-like class/function definitions from any Python file."""
+    agents = []
+    try:
+        with open(filepath, "r", encoding="utf-8", errors="ignore") as f:
+            source = f.read()
+        tree = ast.parse(source, filename=filepath)
+    except (SyntaxError, ValueError, OSError):
+        return agents
+
+    for node in ast.walk(tree):
+        # Classes with "Agent" in the name
+        if isinstance(node, ast.ClassDef) and "agent" in node.name.lower():
+            agents.append({
+                "name": node.name,
+                "type": "class",
+                "file": filepath,
+                "line": node.lineno,
+                "role": classify_role(node.name, _get_docstring(node)),
+                "tools": _extract_tool_refs(node),
+                "confidence": 0.7,
+            })
+
+        # Functions decorated with @agent or similar
+        if isinstance(node, ast.FunctionDef):
+            decorators = _get_decorator_names(node)
+            if any(d in ("agent", "crew", "tool") for d in decorators):
+                agents.append({
+                    "name": node.name,
+                    "type": "decorated_function",
+                    "decorator": [d for d in decorators if d in ("agent", "crew", "tool")][0],
+                    "file": filepath,
+                    "line": node.lineno,
+                    "role": classify_role(node.name, _get_docstring(node)),
+                    "tools": _extract_tool_refs(node),
+                    "confidence": 0.9,
+                })
+
+        # Functions using AgentExecutor or in agents/ directory
+        if isinstance(node, ast.FunctionDef):
+            is_agent_function = False
+            reason = ""
+
+            # Check if function name contains agent-related patterns
+            name_lower = node.name.lower()
+            if any(kw in name_lower for kw in ("agent", "workflow", "pipeline")):
+                is_agent_function = True
+                reason = "name_pattern"
+
+            # Check if function body references AgentExecutor
+            if not is_agent_function:
+                for child in ast.walk(node):
+                    if isinstance(child, ast.Name) and child.id == "AgentExecutor":
+                        is_agent_function = True
+                        reason = "AgentExecutor_usage"
+                        break
+                    if isinstance(child, ast.Attribute) and child.attr == "AgentExecutor":
+                        is_agent_function = True
+                        reason = "AgentExecutor_usage"
+                        break
+
+            # Check if file is in an agents/ directory
+            if not is_agent_function and "/agents/" in filepath:
+                is_agent_function = True
+                reason = "agents_directory"
+
+            # Skip if already captured as decorated function
+            decorators = _get_decorator_names(node)
+            if is_agent_function and not any(d in ("agent", "crew", "tool") for d in decorators):
+                agents.append({
+                    "name": node.name,
+                    "type": "function_agent",
+                    "detection": reason,
+                    "file": filepath,
+                    "line": node.lineno,
+                    "role": classify_role(node.name, _get_docstring(node)),
+                    "tools": _extract_tool_refs(node),
+                    "confidence": 0.6,
+                })
+
+        # Agent() instantiation calls
+        if isinstance(node, ast.Call):
+            func_name = _get_call_name(node)
+            if func_name and "agent" in func_name.lower():
+                name = _infer_agent_name(node, source, filepath)
+                agents.append({
+                    "name": name,
+                    "type": "instantiation",
+                    "constructor": func_name,
+                    "file": filepath,
+                    "line": node.lineno,
+                    "role": classify_role(name, _extract_kwargs_str(node, "role", "goal", "description")),
+                    "tools": _extract_tools_kwarg(node),
+                    "kwargs": _extract_kwargs_str(node, "role", "goal", "backstory", "model"),
+                    "confidence": 0.8,
+                })
+
+    return agents
+
+
+def classify_role(name: str, context: str = "") -> str:
+    """Classify agent role based on name and context."""
+    text = f"{name} {context}".lower()
+    scores = {}
+    for role, keywords in ROLE_KEYWORDS.items():
+        scores[role] = sum(1 for kw in keywords if kw in text)
+    if max(scores.values()) == 0:
+        return "unknown"
+    return max(scores, key=scores.get)
+
+
+def map_communication(agents: list) -> dict:
+    """Build a communication graph from agent references."""
+    agent_names = {a["name"].lower() for a in agents}
+    edges = []
+
+    for agent in agents:
+        filepath = agent["file"]
+        try:
+            with open(filepath, "r", encoding="utf-8", errors="ignore") as f:
+                source = f.read()
+        except OSError:
+            continue
+
+        for other_name in agent_names:
+            if other_name == agent["name"].lower():
+                continue
+            if other_name in source.lower():
+                edges.append({
+                    "from": agent["name"],
+                    "to": other_name,
+                    "file": filepath,
+                })
+
+    # Detect patterns
+    nodes = [a["name"] for a in agents]
+    pattern = "unknown"
+    if not edges:
+        pattern = "isolated"
+    elif _has_cycle(nodes, edges):
+        pattern = "circular"
+    elif _is_hierarchical(nodes, edges):
+        pattern = "hierarchical"
+    elif _is_sequential(nodes, edges):
+        pattern = "sequential"
+    else:
+        pattern = "collaborative"
+
+    return {
+        "nodes": nodes,
+        "edges": edges,
+        "pattern": pattern,
+    }
+
+
+def analyze(root: str, framework: str = None) -> dict:
+    """Run full agent analysis."""
+    start = time.time()
+    root = os.path.abspath(root)
+    files = find_python_files(root)
+
+    all_agents = []
+    for f in files:
+        all_agents.extend(extract_agents_generic(f))
+
+    # Deduplicate by name+file
+    seen = set()
+    unique = []
+    for a in all_agents:
+        key = (a["name"], a["file"])
+        if key not in seen:
+            seen.add(key)
+            unique.append(a)
+
+    comm_graph = map_communication(unique)
+
+    # Collect shared tools
+    tool_usage = {}
+    for agent in unique:
+        for tool in agent.get("tools", []):
+            tool_usage.setdefault(tool, []).append(agent["name"])
+    shared_tools = {t: agents for t, agents in tool_usage.items() if len(agents) > 1}
+
+    # Role distribution
+    role_dist = {}
+    for a in unique:
+        role = a.get("role", "unknown")
+        role_dist[role] = role_dist.get(role, 0) + 1
+
+    return {
+        "agents": unique,
+        "agent_count": len(unique),
+        "communication": comm_graph,
+        "shared_tools": shared_tools,
+        "role_distribution": role_dist,
+        "stats": {
+            "files_scanned": len(files),
+            "duration_ms": int((time.time() - start) * 1000),
+        },
+    }
+
+
+# --- Helpers ---
+
+def _get_decorator_names(node: ast.FunctionDef) -> list:
+    names = []
+    for d in node.decorator_list:
+        if isinstance(d, ast.Name):
+            names.append(d.id)
+        elif isinstance(d, ast.Attribute):
+            names.append(d.attr)
+        elif isinstance(d, ast.Call):
+            if isinstance(d.func, ast.Name):
+                names.append(d.func.id)
+            elif isinstance(d.func, ast.Attribute):
+                names.append(d.func.attr)
+    return names
+
+
+def _get_call_name(node: ast.Call) -> str:
+    if isinstance(node.func, ast.Name):
+        return node.func.id
+    if isinstance(node.func, ast.Attribute):
+        return node.func.attr
+    return None
+
+
+def _get_docstring(node) -> str:
+    if node.body and isinstance(node.body[0], ast.Expr):
+        if isinstance(node.body[0].value, ast.Constant) and isinstance(node.body[0].value.value, str):
+            return node.body[0].value.value
+    return ""
+
+
+def _extract_tool_refs(node) -> list:
+    """Extract tool references from a class or function body."""
+    tools = []
+    for child in ast.walk(node):
+        if isinstance(child, ast.Constant) and isinstance(child.value, str):
+            val = child.value.lower()
+            if "tool" in val and len(child.value) < 50:
+                tools.append(child.value)
+    return tools[:10]
+
+
+def _extract_tools_kwarg(node: ast.Call) -> list:
+    """Extract tools from Agent(tools=[...]) kwarg."""
+    for kw in node.keywords:
+        if kw.arg == "tools":
+            if isinstance(kw.value, ast.List):
+                items = []
+                for elt in kw.value.elts:
+                    if isinstance(elt, ast.Name):
+                        items.append(elt.id)
+                    elif isinstance(elt, ast.Constant):
+                        items.append(str(elt.value))
+                return items
+    return []
+
+
+def _extract_kwargs_str(node: ast.Call, *keys) -> str:
+    """Extract string kwargs from a Call node."""
+    parts = []
+    for kw in node.keywords:
+        if kw.arg in keys and isinstance(kw.value, ast.Constant):
+            parts.append(str(kw.value.value))
+    return " ".join(parts)
+
+
+def _infer_agent_name(node: ast.Call, source: str, filepath: str) -> str:
+    """Try to infer agent name from variable assignment or kwargs."""
+    for kw in node.keywords:
+        if kw.arg in ("name", "role") and isinstance(kw.value, ast.Constant):
+            return str(kw.value.value)
+    # Fall back to variable name from assignment context
+    lines = source.split("\n")
+    if node.lineno <= len(lines):
+        line = lines[node.lineno - 1]
+        match = re.match(r"(\w+)\s*=", line)
+        if match:
+            return match.group(1)
+    return f"agent_at_{Path(filepath).stem}_{node.lineno}"
+
+
+def _has_cycle(nodes: list, edges: list) -> bool:
+    adj = {n: [] for n in nodes}
+    for e in edges:
+        if e["from"] in adj:
+            adj[e["from"]].append(e["to"])
+    visited = set()
+    rec_stack = set()
+
+    def dfs(node):
+        visited.add(node)
+        rec_stack.add(node)
+        for neighbor in adj.get(node, []):
+            if neighbor not in visited:
+                if dfs(neighbor):
+                    return True
+            elif neighbor in rec_stack:
+                return True
+        rec_stack.discard(node)
+        return False
+
+    for n in nodes:
+        if n not in visited:
+            if dfs(n):
+                return True
+    return False
+
+
+def _is_hierarchical(nodes: list, edges: list) -> bool:
+    in_degree = {n: 0 for n in nodes}
+    for e in edges:
+        to = e["to"]
+        if to in in_degree:
+            in_degree[to] += 1
+    roots = [n for n, d in in_degree.items() if d == 0]
+    return len(roots) == 1 and len(edges) >= len(nodes) - 1
+
+
+def _is_sequential(nodes: list, edges: list) -> bool:
+    if len(edges) != len(nodes) - 1:
+        return False
+    out_degree = {}
+    for e in edges:
+        out_degree[e["from"]] = out_degree.get(e["from"], 0) + 1
+    return all(d <= 1 for d in out_degree.values())
+
+
+def main():
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Analyze agent topology")
+    parser.add_argument("--path", default=".", help="Directory to scan")
+    parser.add_argument("--framework", default=None, help="Framework hint")
+    args = parser.parse_args()
+
+    result = analyze(args.path, framework=args.framework)
+    print(json.dumps(result, indent=2, default=str))
+
+
+if __name__ == "__main__":
+    main()