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

agent_toolkit/compiler/targets/__init__.py

@@ -0,0 +1 @@
+"""Target adapters — compile canonical IR into native platform artifacts."""

agent_toolkit/compiler/targets/agent_plugins.py

@@ -0,0 +1,160 @@
+"""
+Agent Plugins 1.0 target adapter — portable plugin format.
+
+Compiles canonical IR into Agent Plugins 1.0 compliant bundles:
+  plugins/<product-id>/plugin.json      — manifest with $schema
+  plugins/<product-id>/skills/<name>/SKILL.md
+  plugins/<product-id>/mcp.json         — if product includes MCP
+  plugins/<product-id>/com.anthropic.claude-code/ — extension dir (agents/hooks)
+
+Spec: https://agent-plugins.org/ + https://github.com/agentplugins/agent-plugins-spec
+Clients: Cursor, VS Code, GitHub Copilot, ChatGPT/Codex, Kiro — NOT Claude Code (legacy .claude-plugin kept).
+
+This adapter is the source of truth for the plugin root manifest; bump-version preserves $schema.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from agent_toolkit.compiler.model import CanonicalGraph, CompilationResult, Product, Skill
+from agent_toolkit.compiler.targets.base import TargetAdapter
+
+
+class AgentPluginsAdapter(TargetAdapter):
+    """Compiles products into Agent Plugins 1.0 portable bundles."""
+
+    target_id = "agent-plugins"
+    package_type = "plugin"
+    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
+
+        # 1. Emit portable manifest at plugin root
+        plugin_json = self._build_plugin_json(product)
+        self._write_file(
+            out_dir / "plugin.json",
+            json.dumps(plugin_json, indent=2) + "\n",
+            result,
+        )
+        result.emitted.append("plugin-manifest")
+
+        # 2. Emit skills (Agent Skills spec, immediate children of 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 MCP if included
+        from agent_toolkit.compiler.registry_emit import (
+            mcp_json_text_agent_plugins,
+            resolve_mcp_ids,
+        )
+
+        # We need to support both legacy mcp registry and new agent-plugins mcp.json
+        # For now, emit mcp.json if product has mcp
+        try:
+            mcp_ids = resolve_mcp_ids(
+                product.included_mcp,
+                target_id=self.target_id,
+                registry_dir=self.repo_root / "mcp" / "registry",
+                emit_registries=emit_registries,
+            )
+            if mcp_ids:
+                mcp_text = mcp_json_text_agent_plugins(
+                    mcp_ids, self.repo_root / "mcp" / "registry", self.target_id
+                )
+                if mcp_text:
+                    self._write_file(out_dir / "mcp.json", mcp_text, result)
+                    result.emitted.append("mcp")
+        except Exception as e:
+            result.warnings.append(f"MCP emit failed: {e}")
+
+        # 4. Document non-portable components (agents/hooks) as extension
+        if product.included_agents or product.included_hooks:
+            result.unsupported.append(
+                "agents/hooks are not portable in Agent Plugins 1.0 — emitted via com.anthropic.claude-code/ extension (ignored by portable clients)"
+            )
+
+        return result
+
+    def _build_plugin_json(self, product: Product) -> dict:
+        try:
+            from agent_toolkit import __version__
+
+            version = __version__
+        except ImportError:
+            version = "1.0.0"
+
+        # Map product id to keywords
+        keywords = ["agent-toolkit", product.id.replace("agent-toolkit-", "")]
+        if product.id == "agent-toolkit-core":
+            keywords = ["agent-toolkit", "core", "skills", "agents"]
+        elif product.id == "agent-toolkit-complete":
+            keywords = ["agent-toolkit", "complete", "skills", "agents", "mcp"]
+
+        return {
+            "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+            "name": product.id,
+            "version": version,
+            "description": product.description,
+            "author": {
+                "name": "ulises-jeremias",
+                "url": "https://github.com/ulises-jeremias/agent-toolkit",
+            },
+            "homepage": "https://github.com/ulises-jeremias/agent-toolkit",
+            "repository": "https://github.com/ulises-jeremias/agent-toolkit",
+            "license": "MIT",
+            "keywords": keywords,
+            "extensions": {
+                "com.anthropic.claude-code": {
+                    "agents": "agents/",
+                    "hooks": "hooks/",
+                    "skills": "skills/",
+                },
+                "com.agent-toolkit.cli": {
+                    "product": product.id,
+                    "stability": product.stability.value
+                    if hasattr(product.stability, "value")
+                    else str(product.stability),
+                },
+            },
+        }
+
+    def _emit_skill(self, skill: Skill, out_dir: Path, result: CompilationResult) -> None:
+        if not skill.source_path.exists():
+            result.warnings.append(f"Skill source not found: {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)
+        self._copy_skill_references(skill, dst, result)
+        result.emitted.append(f"skill:{skill.id}")
+
+    def _copy_skill_references(
+        self, skill: Skill, dst: Path, result: CompilationResult, *, text_mode: bool = False
+    ) -> None:
+        # Copy references/ if present (text_mode kept for base compatibility)
+        src_ref = skill.source_path.parent / "references"
+        if src_ref.is_dir():
+            import shutil
+
+            dst_ref = dst / "references"
+            if dst_ref.exists():
+                shutil.rmtree(dst_ref)
+            shutil.copytree(src_ref, dst_ref)
+            result.emitted.append(f"skill:{skill.id}:references")

agent_toolkit/compiler/targets/base.py

@@ -0,0 +1,229 @@
+"""Abstract base for target adapters."""
+
+from __future__ import annotations
+
+import re
+import tempfile
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from agent_toolkit.compiler.model import CanonicalGraph, CompilationResult, Product, Skill
+from agent_toolkit.compiler.provenance import ArtifactRecord, file_digest, write_provenance
+
+
+class PathEscapeError(ValueError):
+    """Raised when a path resolves outside its containment root."""
+
+
+# Private LAN markers for public plugin/package manifests.
+# Use IP regexes (not bare "10.") so semver like 1.10.0 does not false-positive.
+_PRIVATE_IPV4_10 = re.compile(r"\b10\.\d{1,3}\.\d{1,3}\.\d{1,3}\b")
+_PRIVATE_IPV4_192 = re.compile(r"\b192\.168\.\d{1,3}\.\d{1,3}\b")
+_PRIVATE_IPV4_172 = re.compile(r"\b172\.(?:1[6-9]|2\d|3[0-1])\.\d{1,3}\.\d{1,3}\b")
+_LOCAL_HOSTNAME = re.compile(r"(?:https?://[^\s\"']*|\b)[a-z0-9-]+\.local\b", re.I)
+
+
+def private_network_leak_errors(text: str, *, context: str) -> list[str]:
+    """Return error messages when *text* embeds private hostnames/IPs."""
+    errors: list[str] = []
+    if _PRIVATE_IPV4_10.search(text):
+        errors.append(
+            f"Possible private hostname '10.x' in {context} — "
+            "public distributions must never contain machine-specific URLs"
+        )
+    if _PRIVATE_IPV4_192.search(text):
+        errors.append(
+            f"Possible private hostname '192.168.x' in {context} — "
+            "public distributions must never contain machine-specific URLs"
+        )
+    if _PRIVATE_IPV4_172.search(text):
+        errors.append(
+            f"Possible private hostname '172.16-31.x' in {context} — "
+            "public distributions must never contain machine-specific URLs"
+        )
+    if _LOCAL_HOSTNAME.search(text):
+        errors.append(
+            f"Possible private hostname '.local' in {context} — "
+            "public distributions must never contain machine-specific URLs"
+        )
+    return errors
+
+
+class TargetAdapter(ABC):
+    """Base class for all target adapters."""
+
+    target_id: str = ""
+    package_type: str = ""
+    maturity: str = "stable"
+
+    def __init__(self, output_root: Path, repo_root: Path):
+        self.output_root = output_root
+        self.repo_root = repo_root
+        self._provenance_records: list[ArtifactRecord] = []
+
+    @abstractmethod
+    def compile(
+        self,
+        graph: CanonicalGraph,
+        product: Product,
+    ) -> CompilationResult:
+        """Compile canonical IR into target-specific artifacts."""
+
+    def check(self, graph: CanonicalGraph, product: Product) -> CompilationResult:
+        """Dry-run: validate without writing any files to disk."""
+        with tempfile.TemporaryDirectory(prefix="agent-toolkit-check-") as tmpdir:
+            real_output_root = self.output_root
+            self.output_root = Path(tmpdir)
+            self._provenance_records = []
+            try:
+                result = self.compile(graph, product)
+            finally:
+                self.output_root = real_output_root
+                self._provenance_records = []
+        result.artifacts.clear()
+        return result
+
+    def _write_file(
+        self,
+        path: Path,
+        content: str,
+        result: CompilationResult,
+        *,
+        source_file: str | Path | None = None,
+    ) -> None:
+        """Write content to path and record it in result.artifacts (+ provenance)."""
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+        result.artifacts.append(path)
+        source = str(source_file) if source_file is not None else "generated"
+        try:
+            rel = str(path.relative_to(self.output_root))
+        except ValueError:
+            rel = path.name
+        src_path = Path(source_file) if source_file is not None else None
+        self._provenance_records.append(
+            ArtifactRecord(
+                path=rel,
+                source_file=source,
+                source_digest=file_digest(src_path) if src_path and src_path.exists() else "n/a",
+                generated_digest=file_digest(path),
+            )
+        )
+
+    def _finalize_provenance(self, product: Product, result: CompilationResult) -> None:
+        """Write .provenance.json under the product output directory (#67)."""
+        out_dir = self.output_root / product.id
+        if not out_dir.exists():
+            return
+        path = write_provenance(
+            out_dir,
+            product.id,
+            self.target_id,
+            list(self._provenance_records),
+        )
+        result.artifacts.append(path)
+        result.emitted.append("provenance")
+        self._provenance_records = []
+
+    def _cleanup_stale_artifacts(self, product: Product, result: CompilationResult) -> None:
+        """Remove files under product output that were not emitted this compile (#69)."""
+        out_dir = self.output_root / product.id
+        if not out_dir.is_dir():
+            return
+        keep = {p.resolve() for p in result.artifacts if p.exists()}
+        removed = 0
+        for path in sorted(out_dir.rglob("*"), reverse=True):
+            if not path.is_file():
+                continue
+            if path.resolve() in keep:
+                continue
+            path.unlink(missing_ok=True)
+            removed += 1
+        for path in sorted(out_dir.rglob("*"), reverse=True):
+            if path.is_dir():
+                try:
+                    path.rmdir()
+                except OSError:
+                    pass
+        if removed:
+            result.emitted.append(f"stale-cleaned:{removed}")
+
+    def _safe_relpath(self, file: Path, root: Path) -> Path:
+        """Return *file* relative to *root* after resolving symlinks.
+
+        Raises PathEscapeError when the resolved path is not under *root*.
+        """
+        root_resolved = root.resolve()
+        file_resolved = file.resolve()
+        try:
+            return file_resolved.relative_to(root_resolved)
+        except ValueError as exc:
+            raise PathEscapeError(
+                f"Path escapes containment root {root}: {file} -> {file_resolved}"
+            ) from exc
+
+    def _iter_contained_files(
+        self,
+        root: Path,
+        result: CompilationResult,
+        *,
+        label: str = "",
+    ) -> list[Path]:
+        """List files under *root*, skipping entries that escape after symlink resolution."""
+        if not root.is_dir():
+            return []
+
+        root_resolved = root.resolve()
+        prefix = f"{label}: " if label else ""
+        safe: list[Path] = []
+
+        for path in sorted(root.rglob("*")):
+            if path.is_dir():
+                continue
+            try:
+                resolved = path.resolve()
+            except OSError as exc:
+                result.errors.append(f"{prefix}cannot resolve {path}: {exc}")
+                continue
+            if not resolved.is_file():
+                continue
+            try:
+                resolved.relative_to(root_resolved)
+            except ValueError:
+                result.errors.append(f"{prefix}reference escapes containment root {root}: {path}")
+                continue
+            safe.append(path)
+
+        return safe
+
+    def _copy_skill_references(
+        self,
+        skill: Skill,
+        dst: Path,
+        result: CompilationResult,
+        *,
+        text_mode: bool = False,
+    ) -> None:
+        """Copy skill ``references/`` into *dst* with path containment checks."""
+        refs_src = skill.source_path.parent / "references"
+        if not refs_src.is_dir():
+            return
+
+        skill_root = skill.source_path.parent
+        label = f"skill:{skill.id}"
+
+        for ref_file in self._iter_contained_files(refs_src, result, label=label):
+            try:
+                rel = self._safe_relpath(ref_file, skill_root)
+            except PathEscapeError as exc:
+                result.errors.append(f"{label}: {exc}")
+                continue
+
+            ref_dst = dst / rel
+            if text_mode:
+                ref_content = ref_file.read_text(encoding="utf-8", errors="replace")
+                self._write_file(ref_dst, ref_content, result, source_file=ref_file)
+            else:
+                ref_dst.parent.mkdir(parents=True, exist_ok=True)
+                ref_dst.write_bytes(ref_file.read_bytes())
+                result.artifacts.append(ref_dst)

agent_toolkit/compiler/targets/claude_code.py

@@ -0,0 +1,241 @@
+"""
+Claude Code target adapter.
+
+Compiles canonical IR into Claude Code plugin bundles:
+  plugins/<product-id>/.claude-plugin/plugin.json
+  plugins/<product-id>/skills/<name>/SKILL.md
+  plugins/<product-id>/agents/<name>/AGENT.md
+  plugins/<product-id>/.mcp.json  (TODO: from MCP registry)
+  plugins/<product-id>/hooks/hooks.json  (TODO: from hooks model)
+
+Official docs: https://code.claude.com/docs/en/plugins
+"""
+
+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
+
+FORBIDDEN_SETTINGS = {
+    "skipDangerousModePermissionPrompt",
+    "autoAcceptPermissions",
+    "disablePermissionPrompts",
+}
+
+
+class ClaudeCodeAdapter(TargetAdapter):
+    """Compiles agent-toolkit products into Claude Code plugin bundles."""
+
+    target_id = "claude-code"
+    package_type = "plugin"
+    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
+        hooks_dir = self.repo_root / "capabilities" / "hooks"
+        mcp_dir = self.repo_root / "mcp" / "registry"
+
+        # Emit plugin.json
+        plugin_json = self._build_plugin_json(product, graph)
+        self._write_file(
+            out_dir / ".claude-plugin" / "plugin.json",
+            json.dumps(plugin_json, indent=2) + "\n",
+            result,
+        )
+        result.emitted.append("plugin-manifest")
+
+        # Emit 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)
+
+        # Emit 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)
+
+        from agent_toolkit.compiler.registry_emit import (
+            hooks_json_text,
+            mcp_json_text,
+            resolve_hook_ids,
+            resolve_mcp_ids,
+        )
+
+        hook_ids = resolve_hook_ids(
+            product.included_hooks,
+            target_id=self.target_id,
+            hooks_dir=hooks_dir,
+            emit_registries=emit_registries,
+        )
+        self._emit_hook_scripts(hook_ids, hooks_dir, out_dir, result)
+        hooks_text = hooks_json_text(
+            hook_ids,
+            hooks_dir,
+            self.target_id,
+            bundle_relative=True,
+        )
+        if hooks_text:
+            self._write_file(out_dir / "hooks" / "hooks.json", hooks_text, result)
+            result.emitted.append("hooks")
+
+        mcp_ids = resolve_mcp_ids(
+            product.included_mcp,
+            target_id=self.target_id,
+            registry_dir=mcp_dir,
+            emit_registries=emit_registries,
+        )
+        mcp_text = mcp_json_text(mcp_ids, mcp_dir, self.target_id)
+        if mcp_text:
+            self._write_file(out_dir / ".mcp.json", mcp_text, result)
+            result.emitted.append("mcp")
+
+        pending: list[str] = []
+        if not hook_ids:
+            pending.append("hooks (hooks/hooks.json — none included for this product)")
+        if not mcp_ids:
+            pending.append(".mcp.json (none included for this product)")
+        result.unsupported.extend(pending)
+
+        return result
+
+    def _build_plugin_json(self, product: Product, graph: CanonicalGraph) -> dict:
+        """Build the .claude-plugin/plugin.json manifest."""
+
+        # Import version from package
+        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-", "")],
+        }
+
+    def _emit_skill(self, skill: Skill, out_dir: Path, result: CompilationResult) -> None:
+        """Copy skill SKILL.md to plugin bundle skills/ directory."""
+        if not skill.source_path.exists():
+            result.warnings.append(f"Skill source not found: {skill.source_path}")
+            result.omitted.append(f"skill:{skill.id}")
+            return
+
+        # Claude Code discovers skills at <plugin-root>/skills/<name>/SKILL.md
+        dst = out_dir / "skills" / skill.name
+        dst.mkdir(parents=True, exist_ok=True)
+
+        # Copy SKILL.md
+        content = skill.source_path.read_text(encoding="utf-8", errors="replace")
+        self._write_file(dst / "SKILL.md", content, result)
+
+        # Copy references/ directory if present
+        self._copy_skill_references(skill, dst, result)
+
+        result.emitted.append(f"skill:{skill.id}")
+
+    def _emit_agent(self, agent: Agent, out_dir: Path, result: CompilationResult) -> None:
+        """Copy agent AGENT.md to plugin bundle agents/ directory."""
+        if not agent.source_path.exists():
+            result.warnings.append(f"Agent source not found: {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}")
+
+    def _emit_hook_scripts(
+        self,
+        hook_ids: list[str],
+        hooks_dir: Path,
+        out_dir: Path,
+        result: CompilationResult,
+    ) -> None:
+        """Copy hook handler scripts into the plugin bundle for bundle-relative commands."""
+        from agent_toolkit.compiler.hook_registry import load_hooks
+        from agent_toolkit.compiler.registry_emit import (
+            hook_script_basename,
+            hook_script_source,
+        )
+
+        registry, _errors = load_hooks(hooks_dir)
+        scripts_dir = out_dir / "hooks" / "scripts"
+        copied: set[str] = set()
+
+        for hook_id in hook_ids:
+            hook = registry.get(hook_id)
+            if hook is None or hook.handler_type != "command" or not hook.command:
+                continue
+            script_name = hook_script_basename(hook.command)
+            if script_name is None or script_name in copied:
+                continue
+            src = hook_script_source(hook.command, self.repo_root)
+            if src is None:
+                result.warnings.append(f"Hook '{hook_id}' script not found: {hook.command[-1]}")
+                continue
+            scripts_dir.mkdir(parents=True, exist_ok=True)
+            dst = scripts_dir / script_name
+            dst.write_bytes(src.read_bytes())
+            dst.chmod(dst.stat().st_mode | 0o111)
+            result.artifacts.append(dst)
+            copied.add(script_name)
+            result.emitted.append(f"hook-script:{script_name}")
+
+    @staticmethod
+    def validate_settings(settings: dict) -> list[str]:
+        """Validate a settings.json for forbidden fields."""
+        return [
+            f"Forbidden setting: {k} — must not ship in public plugin defaults"
+            for k in FORBIDDEN_SETTINGS
+            if k in settings
+        ]
+
+    @staticmethod
+    def parity_notes() -> str:
+        """Return honest parity notes for certification docs."""
+        return (
+            "Claude Code plugin bundles emit skills, agents, and plugin.json under "
+            ".claude-plugin/. Hooks and .mcp.json are not generated yet — reported as "
+            "unsupported until the canonical hook model and MCP registry are wired in.\n"
+            "\n"
+            "Never ship or overwrite ~/.claude/settings.json from public profiles. "
+            "Plugin settings are plugin-local; users enable marketplace plugins in their "
+            "own settings file."
+        )