opencode-codeops 1.4.0

package/scripts/install_agents.py

@@ -0,0 +1,288 @@
+#!/usr/bin/env python3
+"""
+install_agents.py — CodeOps for OpenCode
+Generates OpenCode agent Markdown files from codeops/codeops.json routing config.
+
+Usage:
+  python3 install_agents.py --project <path> --roles ROLE[,ROLE...]
+  python3 install_agents.py --project <path> --check
+  python3 install_agents.py --project <path> --dry-run --roles ROLE[,ROLE...]
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Optional
+
+# ---------------------------------------------------------------------------
+# Role → template-filename mapping (authoritative — drives dispatch resolution)
+# OpenCode resolves agents by filename (sans .md); dispatch packets use role names.
+# ---------------------------------------------------------------------------
+ROLE_TO_TEMPLATE: dict[str, str] = {
+    "explorer":                    "codebase-scout",
+    "design-challenger":           "design-challenger",
+    "performance-auditor":         "perf-auditor",
+    "correctness-reviewer":        "phase-reviewer",
+    "executor":                    "plan-task-executor",
+    "demanding-executor":          "plan-task-executor-opus",
+    "preflight-auditor":           "preflight-auditor",
+    "security-auditor":            "security-auditor",
+    "spec-test-author":            "spec-test-author",
+    "financial-integrity-auditor": "financial-integrity-auditor",
+    "concurrency-auditor":         "concurrency-auditor",
+    "semantics-reviewer":          "semantics-reviewer",
+}
+
+ALL_ROLES = list(ROLE_TO_TEMPLATE.keys())
+
+# Default permissions per template (read-only audit vs full-access executor)
+TEMPLATE_PERMISSIONS: dict[str, dict[str, str]] = {
+    "codebase-scout":            {"read": "allow", "grep": "allow", "glob": "allow", "edit": "deny",  "bash": "deny"},
+    "design-challenger":         {"read": "allow", "grep": "allow", "glob": "allow", "edit": "deny",  "bash": "deny"},
+    "perf-auditor":              {"read": "allow", "grep": "allow", "glob": "allow", "edit": "deny",  "bash": "allow"},
+    "phase-reviewer":            {"read": "allow", "grep": "allow", "glob": "allow", "edit": "deny",  "bash": "allow"},
+    "plan-task-executor":        {"read": "allow", "grep": "allow", "glob": "allow", "edit": "allow", "bash": "allow"},
+    "plan-task-executor-opus":   {"read": "allow", "grep": "allow", "glob": "allow", "edit": "allow", "bash": "allow"},
+    "preflight-auditor":         {"read": "allow", "grep": "allow", "glob": "allow", "edit": "deny",  "bash": "allow"},
+    "security-auditor":          {"read": "allow", "grep": "allow", "glob": "allow", "edit": "deny",  "bash": "allow"},
+    "spec-test-author":          {"read": "allow", "grep": "allow", "glob": "allow", "edit": "allow", "bash": "allow"},
+    "financial-integrity-auditor": {"read": "allow", "edit": "deny",  "bash": "deny"},
+    "concurrency-auditor":       {"read": "allow", "edit": "deny",  "bash": "deny"},
+    "semantics-reviewer":        {"read": "allow", "edit": "deny",  "bash": "deny"},
+}
+
+# effort -> temperature mapping
+EFFORT_TO_TEMPERATURE: dict[str, float] = {
+    "high":   0.1,
+    "medium": 0.2,
+    "low":    0.3,
+}
+
+# sandbox -> permission overrides
+SANDBOX_PERMISSIONS: dict[str, dict[str, str]] = {
+    "read-only":           {"edit": "deny",  "bash": "deny"},
+    "workspace-write":     {"edit": "allow", "bash": "allow"},
+    "danger-full-access":  {"edit": "allow", "bash": "allow"},
+}
+
+CODEOPS_MARKER = "# Generated by CodeOps install_agents.py"
+
+
+def find_plugin_root() -> Optional[Path]:
+    """Locate the opencode-codeops package root via CODEOPS_PLUGIN_ROOT or this script's location."""
+    env_root = os.environ.get("CODEOPS_PLUGIN_ROOT")
+    if env_root and (Path(env_root) / "agent-templates").is_dir():
+        return Path(env_root)
+    # Fallback: this script lives in <package root>/scripts/.
+    script_dir = Path(__file__).parent
+    candidate = script_dir.parent
+    if (candidate / "agent-templates").is_dir():
+        return candidate
+    return None
+
+
+def strip_frontmatter(content: str) -> str:
+    """Remove YAML frontmatter block (--- ... ---) from the top of a Markdown file."""
+    if content.startswith("---"):
+        end = content.find("\n---", 3)
+        if end != -1:
+            return content[end + 4:].lstrip("\n")
+    return content
+
+
+def load_template_body(plugin_root: Path, template_name: str) -> str:
+    """Load and return the body of an agent template (frontmatter stripped)."""
+    path = plugin_root / "agent-templates" / f"{template_name}.md"
+    if not path.exists():
+        raise FileNotFoundError(f"Agent template not found: {path}")
+    return strip_frontmatter(path.read_text(encoding="utf-8"))
+
+
+def build_agent_frontmatter(
+    role: str,
+    template_name: str,
+    description: str,
+    temperature: float,
+    model: Optional[str],
+    permissions: dict[str, str],
+    sandbox: Optional[str],
+) -> str:
+    """Construct the OpenCode agent YAML frontmatter block."""
+    lines = [
+        CODEOPS_MARKER,
+        f"# Role: {role} | Template: {template_name}",
+        "# Do not edit this file manually — regenerate with: install_agents.py",
+        "---",
+        f"description: {description}",
+        "mode: subagent",
+    ]
+    if model:
+        lines.append(f"model: {model}")
+    lines.append(f"temperature: {temperature}")
+    lines.append("hidden: true")
+    lines.append("permission:")
+    for key, value in permissions.items():
+        lines.append(f"  {key}: {value}")
+    if sandbox == "danger-full-access":
+        lines.append("# WARNING: this role has danger-full-access sandbox — review carefully")
+    lines.append("---")
+    return "\n".join(lines) + "\n"
+
+
+def load_template_description(plugin_root: Path, template_name: str) -> str:
+    """Extract description from an agent template's original frontmatter."""
+    path = plugin_root / "agent-templates" / f"{template_name}.md"
+    if not path.exists():
+        return f"CodeOps {template_name} agent"
+    content = path.read_text(encoding="utf-8")
+    m = re.search(r"^description:\s*(.+)$", content, re.MULTILINE)
+    return m.group(1).strip() if m else f"CodeOps {template_name} agent"
+
+
+def generate_agent_file(
+    plugin_root: Path,
+    role: str,
+    role_config: dict,
+) -> str:
+    """Generate the full content of an OpenCode agent .md file for a given role."""
+    template_name = ROLE_TO_TEMPLATE[role]
+
+    # Description from template
+    description = load_template_description(plugin_root, template_name)
+
+    # Temperature from effort
+    effort = role_config.get("effort", "high")
+    temperature = EFFORT_TO_TEMPERATURE.get(effort, 0.1)
+
+    # Model: only set if explicitly configured
+    model: Optional[str] = role_config.get("model") or None
+
+    # Permissions: start from template defaults, then apply sandbox overrides
+    permissions = dict(TEMPLATE_PERMISSIONS.get(template_name, {"read": "allow", "edit": "deny", "bash": "deny"}))
+    sandbox = role_config.get("sandbox")
+    if sandbox and sandbox in SANDBOX_PERMISSIONS:
+        permissions.update(SANDBOX_PERMISSIONS[sandbox])
+
+    frontmatter = build_agent_frontmatter(
+        role=role,
+        template_name=template_name,
+        description=description,
+        temperature=temperature,
+        model=model,
+        permissions=permissions,
+        sandbox=sandbox,
+    )
+    body = load_template_body(plugin_root, template_name)
+    return frontmatter + "\n" + body
+
+
+def is_codeops_generated(path: Path) -> bool:
+    """Return True if the file was generated by this script (has the CodeOps marker)."""
+    if not path.exists():
+        return False
+    first_line = path.read_text(encoding="utf-8").split("\n", 1)[0]
+    return first_line.strip() == CODEOPS_MARKER
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Generate OpenCode agent files from CodeOps routing config."
+    )
+    parser.add_argument("--project", required=True, help="Path to the project root")
+    parser.add_argument("--roles", help="Comma-separated list of roles to install (default: all)")
+    parser.add_argument("--check", action="store_true", help="Check for missing or stale agents without writing")
+    parser.add_argument("--dry-run", action="store_true", help="Show what would be written without writing")
+    args = parser.parse_args()
+
+    project = Path(args.project).resolve()
+    config_path = project / "codeops" / "codeops.json"
+
+    # Load routing config if present
+    routing_roles: dict[str, dict] = {}
+    if config_path.exists():
+        try:
+            cfg = json.loads(config_path.read_text(encoding="utf-8"))
+            routing_roles = cfg.get("routing", {}).get("roles", {})
+        except (json.JSONDecodeError, KeyError) as e:
+            print(f"Warning: could not parse {config_path}: {e}", file=sys.stderr)
+
+    # Determine which roles to process
+    if args.roles:
+        requested = [r.strip() for r in args.roles.split(",")]
+        unknown = [r for r in requested if r not in ROLE_TO_TEMPLATE]
+        if unknown:
+            print(f"Error: unknown roles: {', '.join(unknown)}", file=sys.stderr)
+            print(f"Available roles: {', '.join(ALL_ROLES)}", file=sys.stderr)
+            return 1
+        roles = requested
+    else:
+        roles = ALL_ROLES
+
+    # Find plugin root
+    plugin_root = find_plugin_root()
+    if plugin_root is None:
+        print(
+            "Error: could not locate opencode-codeops plugin root. "
+            "Set CODEOPS_PLUGIN_ROOT or run from within the plugin directory.",
+            file=sys.stderr,
+        )
+        return 1
+
+    agents_dir = project / ".opencode" / "agents"
+
+    if args.check:
+        # Check mode: report missing or stale files
+        issues = []
+        for role in roles:
+            out_path = agents_dir / f"{role}.md"
+            if not out_path.exists():
+                issues.append(f"MISSING: {out_path}")
+            elif not is_codeops_generated(out_path):
+                issues.append(f"HAND-AUTHORED (skip): {out_path}")
+        if issues:
+            print("Agent check found issues:")
+            for i in issues:
+                print(f"  {i}")
+            return 1
+        else:
+            print(f"OK: all {len(roles)} CodeOps agent files present.")
+            return 0
+
+    # Generate and write (or dry-run)
+    if not args.dry_run:
+        agents_dir.mkdir(parents=True, exist_ok=True)
+
+    written = 0
+    skipped = 0
+    for role in roles:
+        out_path = agents_dir / f"{role}.md"
+
+        # Preserve hand-authored files
+        if out_path.exists() and not is_codeops_generated(out_path):
+            print(f"  SKIP (hand-authored): {out_path.name}")
+            skipped += 1
+            continue
+
+        role_config = routing_roles.get(role, {})
+        content = generate_agent_file(plugin_root, role, role_config)
+
+        if args.dry_run:
+            print(f"  [dry-run] would write: {out_path}")
+            print(f"    model={role_config.get('model', '(inherit)')}, "
+                  f"effort={role_config.get('effort', 'high')}, "
+                  f"sandbox={role_config.get('sandbox', 'default')}")
+        else:
+            out_path.write_text(content, encoding="utf-8")
+            print(f"  wrote: {out_path.name}")
+            written += 1
+
+    if not args.dry_run:
+        print(f"\nDone: {written} written, {skipped} skipped (hand-authored).")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())