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

agent_toolkit/compiler/targets/cursor.py

@@ -0,0 +1,207 @@
+"""
+Cursor IDE/CLI target adapter.
+
+Compiles canonical IR into Cursor plugin bundles:
+  plugins/<product-id>/.cursor-plugin/plugin.json   — marketplace manifest
+  plugins/<product-id>/skills/<name>/SKILL.md        — on-demand procedures
+  plugins/<product-id>/agents/<name>/AGENT.md        — agent personas
+
+Key differences from Claude Code:
+- Manifest key is `.cursor-plugin/`, not `.claude-plugin/`
+- Rules (.mdc) are a separate surface from skills:
+    * Rules = persistent behavioral constraints (always-on in session)
+    * Skills = on-demand procedures with resources (invoked explicitly)
+  Rules are generated from agent/assistant instructions; they are NOT
+  a substitute for skills in the plugin bundle.
+- Hook event names differ (workspaceOpen, sessionStart vs session.start)
+- MCP config goes in .cursor/mcp.json, not .mcp.json
+
+Official docs: https://cursor.com/docs/plugins
+Research: docs/research/platform-capability-matrix.md (2026-08-04)
+"""
+
+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
+
+# Cursor supports these .mdc rule frontmatter fields.
+# We generate rules only from skill/agent behavioral constraints —
+# NOT as a substitute for skills in the plugin bundle.
+_CURSOR_RULE_HEADER = """\
+---
+description: {description}
+alwaysApply: {always_apply}
+---
+"""
+
+
+class CursorAdapter(TargetAdapter):
+    """Compiles agent-toolkit products into Cursor plugin bundles.
+
+    Cursor reads both IDE and CLI from the same plugin bundle.
+    The generated bundle is installable via the Cursor marketplace or
+    local plugin development linking.
+
+    Capability parity:
+      native:               skills, agents, plugin manifest
+      native-experimental:  hooks (not yet implemented — pending hook model)
+      manual:               MCP (user configures ~/.cursor/mcp.json separately)
+      unsupported:          Windsurf-style always-on global rules
+    """
+
+    target_id = "cursor"
+    package_type = "plugin"
+    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. Emit .cursor-plugin/plugin.json
+        plugin_json = self._build_plugin_json(product)
+        self._write_file(
+            out_dir / ".cursor-plugin" / "plugin.json",
+            json.dumps(plugin_json, indent=2) + "\n",
+            result,
+        )
+        result.emitted.append("plugin-manifest")
+
+        # 2. Emit skills (same Agent Skills SKILL.md format as Claude Code)
+        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 (AGENT.md format)
+        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 unsupported/pending capabilities
+        #    (never silently drop — always report)
+        result.unsupported.extend(
+            [
+                "hooks (pending canonical hook model — Cursor uses workspaceOpen/sessionStart events)",
+                "mcp (.cursor/mcp.json — user configures manually; not bundled in plugin)",
+                "cursor-rules (.mdc) — generated as a separate profile surface, not in plugin bundle",
+            ]
+        )
+
+        return result
+
+    # ── manifest ──────────────────────────────────────────────────────────────
+
+    def _build_plugin_json(self, product: Product) -> dict:
+        """Build the .cursor-plugin/plugin.json manifest.
+
+        Schema matches Claude Code plugin.json (both platforms share this format),
+        but Cursor resolves plugin root from .cursor-plugin/ not .claude-plugin/.
+        """
+        try:
+            from agent_toolkit import __version__
+
+            version = __version__
+        except ImportError:
+            version = "1.0.0"
+
+        return {
+            "name": product.id,
+            "version": version,
+            "description": product.description,
+            "author": {
+                "name": "ulises-jeremias",
+                "email": "ulisescf.24@gmail.com",
+            },
+            "homepage": "https://github.com/ulises-jeremias/agent-toolkit",
+            "repository": "https://github.com/ulises-jeremias/agent-toolkit",
+            "license": "MIT",
+            "keywords": [
+                "agent-toolkit",
+                product.id.replace("agent-toolkit-", ""),
+                "cursor",
+                "skills",
+                "agents",
+            ],
+        }
+
+    # ── skills ────────────────────────────────────────────────────────────────
+
+    def _emit_skill(self, skill: Skill, out_dir: Path, result: CompilationResult) -> None:
+        """Copy SKILL.md (and references/) into plugin skills/ directory.
+
+        Cursor discovers skills at <plugin-root>/skills/<name>/SKILL.md —
+        the same path as Claude Code. No transformation needed.
+        """
+        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)
+
+        # Copy references/ (progressive disclosure)
+        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 into plugin agents/ directory.
+
+        Cursor discovers agents at <plugin-root>/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 document ───────────────────────────────────────────────────────
+
+    @staticmethod
+    def parity_notes() -> str:
+        """Return honest parity notes for documentation generation."""
+        return (
+            "Cursor IDE and Cursor CLI both read from the same plugin bundle and "
+            "the same ~/.cursor/rules/ directory. No separate surface needed.\n"
+            "\n"
+            "Rules (.mdc files) are generated separately as a profile surface "
+            "(`profiles/cursor/rules/`) for users who install profiles manually. "
+            "They are NOT duplicated inside the plugin bundle because rules represent "
+            "persistent behavioral constraints, not the same semantic as on-demand skills.\n"
+            "\n"
+            "MCP: user configures ~/.cursor/mcp.json independently. The plugin does "
+            "not bundle MCP server configuration (pending MCP registry implementation).\n"
+            "\n"
+            "Hooks: Cursor supports workspaceOpen, sessionStart, sessionEnd, and other "
+            "lifecycle events. These require the canonical hook model to be defined first "
+            "(see issue #16)."
+        )

agent_toolkit/compiler/targets/gemini_cli.py

@@ -0,0 +1,213 @@
+"""
+Gemini CLI extension adapter.
+
+Generates a Gemini CLI extension bundle from the canonical IR.
+
+Official docs:
+  https://github.com/google-gemini/gemini-cli/blob/main/docs/extensions/index.md
+  https://github.com/google-gemini/gemini-cli/blob/main/docs/extensions/reference.md
+Gallery:
+  https://geminicli.com/extensions/
+Research:
+  docs/research/platform-capability-matrix.md (2026-08-04)
+
+Key differences from Claude Code / Cursor:
+- Manifest: gemini-extension.json (at extension root)
+- Commands: TOML format (not YAML frontmatter or Markdown)
+  Skills map to Gemini commands via TOML definitions
+- MCP: native (mcpServers array in gemini-extension.json)
+- Hooks: native (hooks/hooks.json, 8+ events: SessionStart, BeforeTool, etc.)
+- Distribution: GitHub repo or geminicli.com gallery
+- Path variables: use ${extensionPath} (not absolute paths)
+- Context files: NOT a large always-on GEMINI.md — prefer minimal context
+"""
+
+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
+
+# Minimum Gemini CLI version supporting the extension system
+MIN_GEMINI_CLI_VERSION = "0.1.0"
+
+# Gemini uses TOML for commands — we generate a TOML block per skill
+_TOML_COMMAND_TEMPLATE = """\
+[[commands]]
+name = "{name}"
+description = "{description}"
+"""
+
+
+class GeminiCLIAdapter(TargetAdapter):
+    """Compiles agent-toolkit products into Gemini CLI extension bundles.
+
+    Extension is installable via:
+      gemini extensions add ulises-jeremias/agent-toolkit-gemini
+
+    Or linked for local development:
+      gemini extensions link /path/to/extension
+
+    Capability parity:
+      native:              skills (as TOML commands), agents, plugin manifest
+      native:              MCP (mcpServers in gemini-extension.json — pending MCP registry #15)
+      native-experimental: hooks (hooks/hooks.json — pending canonical hook model #16)
+      unsupported:         always-on GEMINI.md (prefer minimal context + commands)
+    """
+
+    target_id = "gemini-cli"
+    package_type = "extension"
+    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. gemini-extension.json manifest
+        manifest = self._build_manifest(product, graph)
+        self._write_file(
+            out_dir / "gemini-extension.json",
+            json.dumps(manifest, indent=2) + "\n",
+            result,
+        )
+        result.emitted.append("extension-manifest")
+
+        # 2. Skills → bundled SKILL.md + TOML commands that inject the body via @{…}
+        commands_toml_lines: list[str] = []
+        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
+            rel_skill = self._emit_skill_file(skill, out_dir, result)
+            if rel_skill is None:
+                continue
+            commands_toml_lines.extend(self._skill_to_toml_command(skill, rel_skill))
+            result.emitted.append(f"skill:{skill_id}")
+
+        if commands_toml_lines:
+            self._write_file(
+                out_dir / "commands.toml",
+                "\n".join(commands_toml_lines) + "\n",
+                result,
+            )
+            result.emitted.append("commands.toml")
+
+        # 3. Agent context files (minimal — not large always-on context)
+        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_context(agent, out_dir, result)
+
+        # 4. Explicitly document pending capabilities
+        result.unsupported.extend(
+            [
+                "hooks (hooks/hooks.json — pending canonical hook model #16)",
+                "mcp (mcpServers — pending MCP registry #15; field reserved in manifest)",
+                "excludeTools (tool restrictions — pending agent model with abstract tools)",
+            ]
+        )
+
+        return result
+
+    def _build_manifest(self, product: Product, graph: CanonicalGraph) -> dict:
+        """Build gemini-extension.json manifest.
+
+        Uses ${extensionPath} variable for bundled resource references.
+        Never uses absolute machine paths.
+        """
+        try:
+            from agent_toolkit import __version__
+
+            version = __version__
+        except ImportError:
+            version = "1.0.0"
+
+        manifest: dict = {
+            "name": product.id,
+            "version": version,
+            "description": product.description,
+            "author": "ulises-jeremias",
+            "repository": "https://github.com/ulises-jeremias/agent-toolkit",
+            "license": "MIT",
+            "geminiCliVersion": f">={MIN_GEMINI_CLI_VERSION}",
+            "contextFiles": [],  # Minimal context — no large always-on files
+            "commands": "${extensionPath}/commands.toml",
+            # MCP servers placeholder — populated by MCP registry (issue #15)
+            # "mcpServers": [],
+            # Hooks placeholder — populated by hook model (issue #16)
+            # "hooks": "${extensionPath}/hooks/hooks.json",
+        }
+        return manifest
+
+    def _emit_skill_file(
+        self, skill: Skill, out_dir: Path, result: CompilationResult
+    ) -> str | None:
+        """Copy SKILL.md into the extension bundle; return path relative to out_dir."""
+        if not skill.source_path.exists():
+            result.warnings.append(f"Skill source missing: {skill.source_path}")
+            result.omitted.append(f"skill:{skill.id}")
+            return None
+
+        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)
+
+        self._copy_skill_references(skill, dst, result, text_mode=True)
+
+        return f"skills/{skill.name}/SKILL.md"
+
+    def _skill_to_toml_command(self, skill: Skill, skill_relpath: str) -> list[str]:
+        """Convert a canonical skill to a Gemini TOML command block.
+
+        Gemini CLI uses TOML for command definitions. The prompt injects the
+        bundled SKILL.md via ``@{path}`` so maturity=stable ships real body
+        content (not a stub pointer).
+        """
+        safe_name = skill.name.replace("-", "_").replace(" ", "_")
+        desc = (skill.description or "").replace('"', "'")[:200]
+
+        lines = [
+            "[[commands]]",
+            f'name = "{safe_name}"',
+            f'description = "{desc}"',
+            'prompt = """',
+            f"Follow the `{skill.name}` skill instructions for {{{{args}}}}.",
+            "",
+            f"@{{{skill_relpath}}}",
+            '"""',
+            "",
+        ]
+        return lines
+
+    def _emit_agent_context(self, agent: Agent, out_dir: Path, result: CompilationResult) -> None:
+        """Emit a minimal agent context file.
+
+        Gemini prefers on-demand commands over large always-on context.
+        We emit a compact context file, not the full 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
+
+        ctx_dir = out_dir / "context"
+        ctx_dir.mkdir(parents=True, exist_ok=True)
+
+        # Copy full AGENT.md for reference — context is opt-in
+        content = agent.source_path.read_text(encoding="utf-8", errors="replace")
+        self._write_file(ctx_dir / f"{agent.name}.md", content, result)
+        result.emitted.append(f"agent:{agent.id}")

agent_toolkit/compiler/targets/muse_code.py

@@ -0,0 +1,113 @@
+"""
+Muse Code target adapter (Meta).
+
+Muse Code (https://developer.meta.com/ai/products/muse-code/) is Meta's agentic CLI for complex coding
+workstreams. It follows the Agent Skills specification:
+
+  Project scope: .agents/skills/<name>/SKILL.md
+  User scope:    ~/.config/muse/skills/<name>/SKILL.md  (XDG: $XDG_CONFIG_HOME/muse)
+
+Muse also supports `muse skills import --from claude|codex` to migrate
+existing skills, and project-local `.agents/skills` which is the primary
+portable contract (AGENTS.md as primary agent contract, .agents/skills
+for skills).
+
+This adapter generates static companion assets for Muse Code:
+
+  skills/<name>/SKILL.md  — on-demand procedures (native SKILL.md format)
+  agents/<name>/AGENT.md  — agent personas (for future muse agent support)
+
+No plugin marketplace exists yet for Muse Code; install is via
+`muse skills install` (personal scope) or git-tracked `.agents/skills`
+(project scope). The adapter therefore uses package_type "skills" and
+maturity "stable".
+
+Install path: `agent-toolkit install --target muse-code` copies skills to
+  ~/.config/muse/skills/ and/or .agents/skills/ via the installer.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from agent_toolkit.compiler.model import (
+    Agent,
+    CanonicalGraph,
+    CompilationResult,
+    Product,
+    Skill,
+)
+from agent_toolkit.compiler.targets.base import TargetAdapter
+
+
+class MuseCodeAdapter(TargetAdapter):
+    """Compiles agent-toolkit products into Muse Code skills."""
+
+    target_id = "muse-code"
+    package_type = "skills"
+    maturity = "stable"
+
+    def compile(
+        self,
+        graph: CanonicalGraph,
+        product: Product,
+        *,
+        emit_registries: bool = False,
+    ) -> CompilationResult:
+        result = CompilationResult(target=self.target_id, product=product.id)
+        out_dir = self.output_root / product.id
+
+        # Emit skills — Muse uses the universal SKILL.md format (Agent Skills spec)
+        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)
+
+        # Emit agents as .agents compatible markdown (future Muse agent support)
+        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)
+
+        self._finalize_provenance(product, result)
+        return result
+
+    def _emit_skill(self, skill: Skill, out_dir: Path, result: CompilationResult) -> None:
+        # Muse prefers `.agents/skills/<name>/SKILL.md` (project) and
+        # `~/.config/muse/skills/<name>/SKILL.md` (user). We emit to `skills/`
+        # which the installer maps to both locations.
+        src = skill.source_path
+        if src and src.is_file():
+            content = src.read_text(encoding="utf-8")
+        else:
+            # Fallback: minimal frontmatter + description
+            content = f"---\nname: {skill.name}\ndescription: {skill.description}\n---\n\n# {skill.name}\n\n{skill.description}\n"
+        dest = out_dir / "skills" / skill.name / "SKILL.md"
+        self._write_file(dest, content, result, source_file=src)
+        result.emitted.append(f"skill:{skill.name}")
+
+    def _emit_agent(self, agent: Agent, out_dir: Path, result: CompilationResult) -> None:
+        src = getattr(agent, "source_path", None)
+        if src and Path(src).is_file():
+            content = Path(src).read_text(encoding="utf-8")
+        else:
+            content = f"---\nname: {agent.name}\ndescription: {getattr(agent, 'description', '')}\n---\n\n# {agent.name}\n"
+        dest = out_dir / "agents" / agent.name / "AGENT.md"
+        self._write_file(dest, content, result, source_file=src)
+        result.emitted.append(f"agent:{agent.name}")
+
+    def _build_plugin_json(self, product: Product, graph: CanonicalGraph | None = None) -> dict:  # noqa: ARG002
+        return {
+            "name": product.id,
+            "version": getattr(product, "version", "0.0.0"),
+            "description": getattr(product, "description", ""),
+            "skills": list(product.included_skills),
+            "agents": list(product.included_agents),
+            "target": self.target_id,
+        }