agent-toolkit-cli 1.11.0__py3-none-win_amd64.whl

agent_toolkit/compiler/targets/opencode.py

@@ -0,0 +1,204 @@
+"""
+OpenCode target adapter.
+
+OpenCode supports two integration surfaces:
+
+1. **Static companion assets** (generated by this adapter):
+   `.opencode/skills/<name>/SKILL.md`    — on-demand procedures
+   `.opencode/agents/<name>/AGENT.md`    — agent personas
+   `.opencode/commands/<name>.md`        — slash commands (future)
+   `opencode.json`                       — minimal, portable model config
+
+   These companion assets work without any runtime code and are
+   discoverable by OpenCode from the project root.
+
+2. **Runtime TypeScript plugin** (NOT implemented here — see issue #10):
+   A proper npm/Bun package in `packages/opencode-plugin/` that exports
+   a plugin function and receives the full OpenCode context API.
+   This is required for lifecycle hooks, custom tools, MCP configuration,
+   and model/tool-call interception.
+
+   The static adapter explicitly reports what requires the runtime plugin.
+
+Official docs: https://opencode.ai/docs/plugins/
+Research: docs/research/platform-capability-matrix.md (2026-08-04)
+
+Key differences from Claude Code/Cursor:
+- No JSON manifest (JS/TS modules, not plugin.json)
+- Distribution: npm or local path (not git marketplace)
+- Skills go in .opencode/skills/, agents in .opencode/agents/
+- opencode.json for model config MUST NOT contain private provider URLs
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from agent_toolkit.compiler.model import (
+    Agent,
+    CanonicalGraph,
+    CompilationResult,
+    Product,
+    Skill,
+)
+from agent_toolkit.compiler.targets.base import TargetAdapter, private_network_leak_errors
+
+# opencode.json safe defaults — NO private providers, NO hardcoded models.
+# Users customize their own ~/.config/opencode/opencode.json.
+_OPENCODE_JSON_TEMPLATE = {
+    "$schema": "https://opencode.ai/config.schema.json",
+}
+
+# opencode.json fields that indicate private/personal configuration.
+# These must never appear in generated output.
+_FORBIDDEN_OPENCODE_FIELDS = {
+    "provider",  # provider config with baseURL can contain private LAN URLs
+}
+
+
+class OpenCodeAdapter(TargetAdapter):
+    """Compiles agent-toolkit products into OpenCode companion assets.
+
+    Generates static companion assets discoverable by OpenCode from the project root.
+    Does NOT generate a runtime TypeScript plugin (that requires packages/opencode-plugin/).
+
+    Capability parity:
+      native (static):  skills (.opencode/skills/), agents (.opencode/agents/)
+      generated:        opencode.json (minimal portable model config)
+      unsupported:      lifecycle hooks, custom tools, MCP config, model interception
+                        (all require the runtime TypeScript plugin — issue #10)
+      unsupported:      plugin marketplace (OpenCode uses npm/git, not marketplace)
+    """
+
+    target_id = "opencode"
+    package_type = "companion-assets"  # NOT a plugin — accurately named
+    maturity = "stable"
+
+    def compile(self, graph: CanonicalGraph, product: Product) -> CompilationResult:
+        result = CompilationResult(target=self.target_id, product=product.id)
+        out_dir = self.output_root / product.id
+
+        # 1. Generate minimal opencode.json (safe defaults only)
+        self._write_file(
+            out_dir / "opencode.json",
+            json.dumps(_OPENCODE_JSON_TEMPLATE, indent=2) + "\n",
+            result,
+        )
+        result.emitted.append("opencode-config")
+
+        # 2. Emit skills to .opencode/skills/
+        for skill_id in product.included_skills:
+            skill = graph.skills.get(skill_id)
+            if skill is None:
+                result.warnings.append(f"Skill '{skill_id}' not found — skipping")
+                result.omitted.append(f"skill:{skill_id}")
+                continue
+            self._emit_skill(skill, out_dir, result)
+
+        # 3. Emit agents to .opencode/agents/
+        for agent_id in product.included_agents:
+            agent = graph.agents.get(agent_id)
+            if agent is None:
+                result.warnings.append(f"Agent '{agent_id}' not found — skipping")
+                result.omitted.append(f"agent:{agent_id}")
+                continue
+            self._emit_agent(agent, out_dir, result)
+
+        # 4. Explicitly document what requires the runtime TypeScript plugin
+        result.unsupported.extend(
+            [
+                "lifecycle hooks — requires packages/opencode-plugin/ TypeScript runtime (issue #10)",
+                "custom tools — requires TypeScript plugin with tool registration API",
+                "MCP server config — requires TypeScript plugin (no static opencode.json format)",
+                "model/tool-call interception — requires TypeScript plugin",
+                "plugin marketplace install — OpenCode uses npm/Bun; no marketplace format",
+            ]
+        )
+
+        return result
+
+    # ── opencode.json ─────────────────────────────────────────────────────────
+
+    @staticmethod
+    def validate_opencode_json(data: dict) -> list[str]:
+        """Return error messages for any forbidden opencode.json fields."""
+        errors = []
+        for field in _FORBIDDEN_OPENCODE_FIELDS:
+            if field in data:
+                errors.append(
+                    f"Forbidden field '{field}' in opencode.json — "
+                    "provider config can contain private LAN URLs and must not ship publicly"
+                )
+        # Check for private hostnames in the whole JSON blob
+        text = json.dumps(data)
+        errors.extend(private_network_leak_errors(text, context="opencode.json"))
+        return errors
+
+    # ── skills ────────────────────────────────────────────────────────────────
+
+    def _emit_skill(self, skill: Skill, out_dir: Path, result: CompilationResult) -> None:
+        """Copy SKILL.md to .opencode/skills/<name>/SKILL.md.
+
+        OpenCode discovers skills at .opencode/skills/<name>/SKILL.md.
+        Same Agent Skills format as Claude Code and Cursor.
+        """
+        if not skill.source_path.exists():
+            result.warnings.append(f"Skill source missing: {skill.source_path}")
+            result.omitted.append(f"skill:{skill.id}")
+            return
+
+        dst = out_dir / ".opencode" / "skills" / skill.name
+        dst.mkdir(parents=True, exist_ok=True)
+
+        content = skill.source_path.read_text(encoding="utf-8", errors="replace")
+        self._write_file(dst / "SKILL.md", content, result)
+
+        # Progressive disclosure: copy references/
+        self._copy_skill_references(skill, dst, result)
+
+        result.emitted.append(f"skill:{skill.id}")
+
+    # ── agents ────────────────────────────────────────────────────────────────
+
+    def _emit_agent(self, agent: Agent, out_dir: Path, result: CompilationResult) -> None:
+        """Copy AGENT.md to .opencode/agents/<name>/AGENT.md."""
+        if not agent.source_path.exists():
+            result.warnings.append(f"Agent source missing: {agent.source_path}")
+            result.omitted.append(f"agent:{agent.id}")
+            return
+
+        dst = out_dir / ".opencode" / "agents" / agent.name
+        dst.mkdir(parents=True, exist_ok=True)
+
+        content = agent.source_path.read_text(encoding="utf-8", errors="replace")
+        self._write_file(dst / "AGENT.md", content, result)
+        result.emitted.append(f"agent:{agent.id}")
+
+    # ── parity notes ──────────────────────────────────────────────────────────
+
+    @staticmethod
+    def typescript_plugin_status() -> str:
+        """Document TypeScript runtime plugin gap for certification."""
+        return (
+            "pending TypeScript runtime plugin — packages/opencode-plugin/ must export "
+            "OpenCode's plugin function for hooks, MCP, custom tools, and tool-call "
+            "interception (issue #10)"
+        )
+
+    @staticmethod
+    def parity_notes() -> str:
+        return (
+            "OpenCode companion assets are static files discoverable from the project "
+            "root. They work without any runtime code.\n"
+            "\n"
+            "The full OpenCode plugin API (lifecycle hooks, custom tools, MCP config, "
+            "model interception) requires a TypeScript package in packages/opencode-plugin/ "
+            "that exports a plugin function receiving the OpenCode context API. "
+            "This is a separate work item (see issue #10).\n"
+            "\n"
+            "opencode.json is generated with safe defaults only (no provider config, "
+            "no hardcoded model). Users customize their own ~/.config/opencode/opencode.json "
+            "for model selection. This prevents the DEFECT-002 class of bugs where "
+            "private LAN URLs get committed to public repositories."
+        )

agent_toolkit/compiler/targets/pi.py

@@ -0,0 +1,263 @@
+"""
+Pi Coding Agent target adapter.
+
+Pi Coding Agent uses npm packages — NOT a plugin marketplace. Packages are
+published to npm (or installed from git) and declare their capabilities via a
+``pi`` field in package.json.
+
+Auto-discovery paths (from research, 2026-08-04):
+  ~/.pi/agent/extensions/*.ts   (global user install)
+  .pi/extensions/*.ts           (project-local install)
+
+This adapter generates **static companion assets only** — no TypeScript runtime
+code is emitted. The companion assets work without any TypeScript and are
+discoverable by Pi from the project root.
+
+1. **Static companion assets** (generated by this adapter):
+   ``pi-package.json``               — package.json declaring ``pi`` field with skills
+   ``skills/<name>/SKILL.md``        — on-demand procedures (native SKILL.md format)
+   ``agents/<name>/AGENT.md``        — agent personas
+
+2. **TypeScript extension** (NOT generated here — see packages/pi-package/):
+   A factory function accepting ExtensionAPI, distributed via npm/pi.dev registry.
+   Required for: lifecycle hooks, custom tools, MCP integration, session state.
+
+Unsupported by this static adapter:
+  - Custom tools (require TypeScript ExtensionAPI)
+  - Lifecycle hooks (require TypeScript ExtensionAPI)
+  - MCP server configuration (no static format — requires TypeScript runtime)
+  - Session state (runtime only)
+  - Plugin marketplace (Pi uses npm / pi.dev registry, not a marketplace)
+
+Research: docs/research/platform-capability-matrix.md (2026-08-04)
+Official registry: https://pi.dev/registry (npm-compatible)
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from agent_toolkit.compiler.model import (
+    Agent,
+    CanonicalGraph,
+    CompilationResult,
+    Product,
+    Skill,
+)
+from agent_toolkit.compiler.targets.base import TargetAdapter, private_network_leak_errors
+
+# Fields that must never appear in a publicly distributed pi-package.json.
+# Private LAN URLs committed to public packages are a DEFECT-002 class bug.
+_FORBIDDEN_PI_FIELDS = {
+    "private",  # marks private packages — companion packs should be public
+}
+
+
+class PiAdapter(TargetAdapter):
+    """Compiles agent-toolkit products into Pi Coding Agent companion assets.
+
+    Pi uses npm package conventions with a ``pi`` field in package.json to
+    declare skills and other capabilities. This adapter generates static
+    companion assets only — no TypeScript code is emitted.
+
+    Capability parity:
+      native (static):  skills (skills/<name>/SKILL.md), agents (agents/<name>/AGENT.md)
+      generated:        pi-package.json (package.json with ``pi`` field)
+      unsupported:      lifecycle hooks, custom tools, MCP integration, session state
+                        (all require TypeScript ExtensionAPI — packages/pi-package/)
+      unsupported:      plugin marketplace (Pi uses npm / pi.dev registry, not a marketplace)
+
+    Note on package_type:
+      Pi does not have a plugin marketplace. ``package_type = "companion-assets"``
+      accurately reflects that this output is a companion npm package of static
+      assets, NOT a marketplace plugin.
+    """
+
+    target_id = "pi"
+    package_type = "companion-assets"  # NOT "plugin" — Pi has no plugin marketplace
+    maturity = "stable"
+
+    def compile(self, graph: CanonicalGraph, product: Product) -> CompilationResult:
+        result = CompilationResult(target=self.target_id, product=product.id)
+        out_dir = self.output_root / product.id
+
+        # 1. Generate pi-package.json (package.json with pi field declaring skills)
+        self._emit_pi_package_json(product, graph, out_dir, result)
+
+        # 2. Emit skills to skills/<name>/SKILL.md
+        for skill_id in product.included_skills:
+            skill = graph.skills.get(skill_id)
+            if skill is None:
+                result.warnings.append(f"Skill '{skill_id}' not found — skipping")
+                result.omitted.append(f"skill:{skill_id}")
+                continue
+            self._emit_skill(skill, out_dir, result)
+
+        # 3. Emit agents to agents/<name>/AGENT.md
+        for agent_id in product.included_agents:
+            agent = graph.agents.get(agent_id)
+            if agent is None:
+                result.warnings.append(f"Agent '{agent_id}' not found — skipping")
+                result.omitted.append(f"agent:{agent_id}")
+                continue
+            self._emit_agent(agent, out_dir, result)
+
+        # 4. Explicitly document what requires the TypeScript ExtensionAPI
+        #    Never silently drop a capability — always report.
+        result.unsupported.extend(
+            [
+                "lifecycle hooks — requires TypeScript ExtensionAPI (packages/pi-package/)",
+                "custom tools — requires TypeScript ExtensionAPI with tool registration",
+                "MCP server config — no static format; requires TypeScript runtime",
+                "session state — runtime only; not expressible in static assets",
+                "plugin marketplace install — Pi uses npm/pi.dev registry, not a marketplace",
+            ]
+        )
+
+        return result
+
+    # ── pi-package.json ───────────────────────────────────────────────────────
+
+    def _emit_pi_package_json(
+        self,
+        product: Product,
+        graph: CanonicalGraph,
+        out_dir: Path,
+        result: CompilationResult,
+    ) -> None:
+        """Generate pi-package.json — package.json with ``pi`` field.
+
+        The ``pi`` field declares which skills are provided by this package.
+        Pi discovers packages from ~/.pi/agent/extensions/*.ts or .pi/extensions/*.ts,
+        but the static companion assets are loaded separately from this manifest.
+
+        Named ``pi-package.json`` (not ``package.json``) so it can coexist with an
+        existing package.json in the project root without collisions.
+        """
+        try:
+            from agent_toolkit import __version__
+
+            version = __version__
+        except ImportError:
+            version = "1.0.0"
+
+        skill_names = []
+        for skill_id in product.included_skills:
+            skill = graph.skills.get(skill_id)
+            if skill is not None:
+                skill_names.append(f"skills/{skill.name}/SKILL.md")
+
+        agent_names = []
+        for agent_id in product.included_agents:
+            agent = graph.agents.get(agent_id)
+            if agent is not None:
+                agent_names.append(f"agents/{agent.name}/AGENT.md")
+
+        pi_package = {
+            "name": f"@agent-toolkit/{product.id}",
+            "version": version,
+            "description": product.description,
+            "license": "MIT",
+            "repository": {
+                "type": "git",
+                "url": "https://github.com/ulises-jeremias/agent-toolkit",
+            },
+            "keywords": [
+                "agent-toolkit",
+                "pi",
+                "skills",
+                "agents",
+                product.id.replace("agent-toolkit-", ""),
+            ],
+            "pi": {
+                "skills": skill_names,
+                "agents": agent_names,
+            },
+        }
+
+        errors = self.validate_pi_package_json(pi_package)
+        for err in errors:
+            result.warnings.append(err)
+
+        self._write_file(
+            out_dir / "pi-package.json",
+            json.dumps(pi_package, indent=2) + "\n",
+            result,
+        )
+        result.emitted.append("pi-package-json")
+
+    @staticmethod
+    def validate_pi_package_json(data: dict) -> list[str]:
+        """Return error messages for any forbidden pi-package.json fields."""
+        errors = []
+        for field in _FORBIDDEN_PI_FIELDS:
+            if field in data and data[field] is True:
+                errors.append(
+                    f"Field '{field}: true' in pi-package.json — "
+                    "companion packs should be publishable (not private)"
+                )
+        text = json.dumps(data)
+        errors.extend(private_network_leak_errors(text, context="pi-package.json"))
+        return errors
+
+    # ── skills ────────────────────────────────────────────────────────────────
+
+    def _emit_skill(self, skill: Skill, out_dir: Path, result: CompilationResult) -> None:
+        """Copy SKILL.md to skills/<name>/SKILL.md.
+
+        Pi uses the native SKILL.md format — same as Claude Code, Cursor, and OpenCode.
+        """
+        if not skill.source_path.exists():
+            result.warnings.append(f"Skill source missing: {skill.source_path}")
+            result.omitted.append(f"skill:{skill.id}")
+            return
+
+        dst = out_dir / "skills" / skill.name
+        dst.mkdir(parents=True, exist_ok=True)
+
+        content = skill.source_path.read_text(encoding="utf-8", errors="replace")
+        self._write_file(dst / "SKILL.md", content, result)
+
+        # Progressive disclosure: copy references/
+        self._copy_skill_references(skill, dst, result)
+
+        result.emitted.append(f"skill:{skill.id}")
+
+    # ── agents ────────────────────────────────────────────────────────────────
+
+    def _emit_agent(self, agent: Agent, out_dir: Path, result: CompilationResult) -> None:
+        """Copy AGENT.md to agents/<name>/AGENT.md."""
+        if not agent.source_path.exists():
+            result.warnings.append(f"Agent source missing: {agent.source_path}")
+            result.omitted.append(f"agent:{agent.id}")
+            return
+
+        dst = out_dir / "agents" / agent.name
+        dst.mkdir(parents=True, exist_ok=True)
+
+        content = agent.source_path.read_text(encoding="utf-8", errors="replace")
+        self._write_file(dst / "AGENT.md", content, result)
+        result.emitted.append(f"agent:{agent.id}")
+
+    # ── parity notes ──────────────────────────────────────────────────────────
+
+    @staticmethod
+    def parity_notes() -> str:
+        return (
+            "Pi Coding Agent companion assets are declared via the ``pi`` field in "
+            "package.json (generated as ``pi-package.json`` here to avoid collisions). "
+            "Skills and agents are static files discoverable without any runtime code.\n"
+            "\n"
+            "Pi does NOT have a plugin marketplace. Packages are distributed via npm "
+            "or the pi.dev registry (npm-compatible). The ``package_type`` for this "
+            "adapter is ``companion-assets`` — not ``plugin``.\n"
+            "\n"
+            "The full Pi ExtensionAPI (lifecycle hooks, custom tools, MCP integration, "
+            "session state) requires a TypeScript factory function exported from an npm "
+            "package. This is a separate work item (see packages/pi-package/).\n"
+            "\n"
+            "Auto-discovery: ~/.pi/agent/extensions/*.ts (global) or "
+            ".pi/extensions/*.ts (project-local). The static companion assets are "
+            "referenced from pi-package.json's ``pi.skills`` and ``pi.agents`` arrays."
+        )