aes-cli 0.2.0__py3-none-any.whl

aes/targets/_base.py

@@ -0,0 +1,77 @@
+"""Base types for sync target adapters."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+# Sentinels embedded in generated files to detect aes sync output
+AES_SENTINEL_MD = "<!-- Generated by `aes sync` \u2014 DO NOT EDIT MANUALLY -->"
+AES_SENTINEL_JSON_KEY = "_aes_sync"
+
+
+@dataclass
+class AgentContext:
+    """Parsed .agent/ contents, passed to every adapter."""
+
+    project_root: Path
+    agent_dir: Path
+    manifest: dict
+    instructions: Optional[str]
+    orchestrator: Optional[str]
+    skill_runbooks: Dict[str, str]
+    permissions: Optional[dict]
+    commands: List[dict]
+    memory_project: Optional[str]
+    skill_metadata: Dict[str, Dict[str, Any]] = field(default_factory=dict)
+    local_config: Optional[dict] = None
+
+
+@dataclass
+class GeneratedFile:
+    """A single file to be generated by sync."""
+
+    relative_path: str
+    content: str
+    description: str
+    action: str = "create"  # create | update | conflict
+
+
+@dataclass
+class SyncPlan:
+    """What a target adapter wants to generate."""
+
+    target_name: str
+    files: List[GeneratedFile] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+
+
+class SyncTarget(ABC):
+    """Abstract base for a tool target adapter."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Tool name, e.g. 'claude'."""
+
+    @abstractmethod
+    def plan(self, ctx: AgentContext, force: bool) -> SyncPlan:
+        """Generate a plan of files to create/update."""
+
+    def _check_conflict(self, project_root: Path, rel_path: str, force: bool) -> str:
+        """Determine the action for a file path.
+
+        Returns 'create', 'update', or 'conflict'.
+        """
+        full_path = project_root / rel_path
+        if not full_path.exists():
+            return "create"
+        content = full_path.read_text()
+        if AES_SENTINEL_MD in content or f'"{AES_SENTINEL_JSON_KEY}"' in content:
+            return "update"
+        if force:
+            return "update"
+        return "conflict"

aes/targets/_composer.py

@@ -0,0 +1,338 @@
+"""Shared composition logic for sync targets."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+
+def compose_instructions(
+    project_name: str,
+    instructions: Optional[str],
+    orchestrator: Optional[str],
+    skill_runbooks: Dict[str, str],
+    memory_project: Optional[str],
+    header: str,
+) -> str:
+    """Compose a single instructions document from .agent/ contents.
+
+    Structure:
+      1. Header (sentinel + title)
+      2. instructions.md
+      3. ORCHESTRATOR.md
+      4. Skill runbooks
+      5. memory/project.md
+    """
+    sections: List[str] = [header]
+
+    if instructions:
+        sections.append(instructions)
+
+    if orchestrator:
+        sections.append("---\n")
+        sections.append(orchestrator)
+
+    if skill_runbooks:
+        sections.append("---\n")
+        sections.append("# Skills Reference\n")
+        for _skill_id, runbook in skill_runbooks.items():
+            sections.append(runbook)
+
+    if memory_project:
+        sections.append("---\n")
+        sections.append(memory_project)
+
+    return "\n\n".join(sections) + "\n"
+
+
+def compose_instructions_with_skill_index(
+    project_name: str,
+    instructions: Optional[str],
+    orchestrator: Optional[str],
+    skill_metadata: Dict[str, Dict[str, Any]],
+    memory_project: Optional[str],
+    header: str,
+    skill_runbooks: Optional[Dict[str, str]] = None,
+) -> str:
+    """Compose instructions with a skill index instead of inlined runbooks.
+
+    Skills are synced as separate command files; this just lists them
+    so the agent knows they exist and can be invoked as slash commands.
+
+    Skills with ``activation: auto`` have their description (and optionally
+    a runbook summary) inlined directly so the agent can match them without
+    invoking a slash command.  ``hybrid`` skills appear in both sections.
+    """
+    sections: List[str] = [header]
+
+    if instructions:
+        sections.append(instructions)
+
+    if orchestrator:
+        sections.append("---\n")
+        sections.append(orchestrator)
+
+    if skill_metadata:
+        # Partition skills by activation mode
+        auto_skills: Dict[str, Dict[str, Any]] = {}
+        explicit_skills: Dict[str, Dict[str, Any]] = {}
+        for skill_id, meta in skill_metadata.items():
+            mode = meta.get("activation", "explicit")
+            if mode in ("auto", "hybrid"):
+                auto_skills[skill_id] = meta
+            if mode in ("explicit", "hybrid"):
+                explicit_skills[skill_id] = meta
+
+        # Auto-activated skills — inlined into instructions
+        if auto_skills:
+            sections.append("---\n")
+            auto_lines: List[str] = [
+                "# Auto-Activated Skills\n",
+                "The following skills activate automatically based on context:\n",
+            ]
+            for skill_id, meta in auto_skills.items():
+                name = meta.get("name", skill_id)
+                desc = meta.get("description", "")
+                neg = meta.get("negative_triggers", [])
+                auto_lines.append(f"### {name} (`/skills/{skill_id}`)\n")
+                if desc:
+                    auto_lines.append(desc)
+                if neg:
+                    auto_lines.append("")
+                    for trigger in neg:
+                        auto_lines.append(f"- {trigger}")
+                perms = format_skill_permissions(meta.get("allowed_tools"))
+                if perms:
+                    auto_lines.append("")
+                    auto_lines.append(perms)
+                auto_lines.append("")
+            sections.append("\n".join(auto_lines))
+
+        # Explicit skills — listed as slash commands
+        if explicit_skills:
+            sections.append("---\n")
+            lines: List[str] = [
+                "# Available Skills\n",
+                "The following skills are available as slash commands:\n",
+            ]
+            for skill_id, meta in explicit_skills.items():
+                name = meta.get("name", skill_id)
+                desc = meta.get("description", "")
+                neg = meta.get("negative_triggers", [])
+                line = f"- **/skills/{skill_id}** — {name}"
+                if desc:
+                    line += f": {desc}"
+                if neg:
+                    line += " " + " ".join(f"[{t}]" for t in neg)
+                lines.append(line)
+            sections.append("\n".join(lines))
+
+    if memory_project:
+        sections.append("---\n")
+        sections.append(memory_project)
+
+    return "\n\n".join(sections) + "\n"
+
+
+def format_skill_permissions(allowed_tools: Optional[Dict[str, Any]]) -> str:
+    """Format per-skill allowed_tools as a markdown permissions note.
+
+    Returns empty string if no permissions are specified.
+    """
+    if not allowed_tools:
+        return ""
+
+    parts: List[str] = ["**Permissions:**"]
+
+    shell = allowed_tools.get("shell")
+    if shell is not None:
+        parts.append(f"- Shell: {'allowed' if shell else 'denied'}")
+
+    files = allowed_tools.get("files")
+    if isinstance(files, dict):
+        read_val = files.get("read")
+        write_val = files.get("write")
+        if read_val is not None:
+            if isinstance(read_val, bool):
+                parts.append(f"- File read: {'allowed' if read_val else 'denied'}")
+            elif isinstance(read_val, list):
+                parts.append(f"- File read: {', '.join(f'`{p}`' for p in read_val)}")
+        if write_val is not None:
+            if isinstance(write_val, bool):
+                parts.append(f"- File write: {'allowed' if write_val else 'denied'}")
+            elif isinstance(write_val, list):
+                parts.append(f"- File write: {', '.join(f'`{p}`' for p in write_val)}")
+
+    network = allowed_tools.get("network")
+    if network is not None:
+        parts.append(f"- Network: {'allowed' if network else 'denied'}")
+
+    mcp = allowed_tools.get("mcp_servers")
+    if mcp:
+        parts.append(f"- MCP servers: {', '.join(mcp)}")
+
+    if len(parts) <= 1:
+        return ""
+
+    return "\n".join(parts)
+
+
+def translate_permissions_to_claude(permissions: dict) -> dict:
+    """Translate AES permissions.yaml into Claude settings.local.json format.
+
+    Claude permissions use patterns like:
+      - Bash(git status*) for shell commands
+      - Read(*) for file reading
+      - Write(src/**) / Edit(src/**) for file writing
+    """
+    allowed: List[str] = []
+    denied: List[str] = []
+
+    # --- allow section ---
+    allow = permissions.get("allow", {})
+
+    allow_shell = allow.get("shell", {})
+    if isinstance(allow_shell, dict):
+        for category in ("read", "execute", "remote"):
+            for pattern in _normalize_patterns(allow_shell.get(category)):
+                allowed.append(f"Bash({pattern})")
+    elif isinstance(allow_shell, list):
+        for pattern in allow_shell:
+            allowed.append(f"Bash({pattern})")
+
+    allow_files = allow.get("files", {})
+    for p in _normalize_patterns(allow_files.get("read")):
+        allowed.append(f"Read({p})")
+    for p in _normalize_patterns(allow_files.get("write")):
+        allowed.append(f"Write({p})")
+        allowed.append(f"Edit({p})")
+    for p in _normalize_patterns(allow_files.get("create")):
+        allowed.append(f"Write({p})")
+
+    # --- deny section ---
+    deny = permissions.get("deny", {})
+
+    deny_shell = deny.get("shell", {})
+    if isinstance(deny_shell, list):
+        for pattern in deny_shell:
+            denied.append(f"Bash({pattern})")
+    elif isinstance(deny_shell, dict):
+        for category in ("read", "execute", "remote"):
+            for pattern in _normalize_patterns(deny_shell.get(category)):
+                denied.append(f"Bash({pattern})")
+
+    deny_files = deny.get("files", {})
+    for p in _normalize_patterns(deny_files.get("write")):
+        denied.append(f"Write({p})")
+        denied.append(f"Edit({p})")
+    for p in _normalize_patterns(deny_files.get("delete")):
+        denied.append(f"Write({p})")
+
+    # --- overrides escape hatch ---
+    overrides = permissions.get("overrides", {}).get("claude", {})
+    override_perms = overrides.get("permissions", {})
+    if override_perms.get("allow"):
+        allowed.extend(override_perms["allow"])
+    if override_perms.get("deny"):
+        denied.extend(override_perms["deny"])
+
+    result: dict = {"permissions": {}}
+    if allowed:
+        result["permissions"]["allow"] = sorted(set(allowed))
+    if denied:
+        result["permissions"]["deny"] = sorted(set(denied))
+
+    return result
+
+
+def translate_permissions_to_markdown(permissions: dict) -> str:
+    """Translate AES permissions.yaml into a markdown restrictions section.
+
+    Used by Cursor, Copilot, and Windsurf targets which don't have structured
+    permission formats — they rely on markdown instructions instead.
+    """
+    sections: List[str] = []
+
+    # --- Allow: file scope ---
+    allow = permissions.get("allow", {})
+    allow_files = allow.get("files", {})
+    write_patterns = _normalize_patterns(allow_files.get("write"))
+    if write_patterns:
+        sections.append("### File Scope\n")
+        sections.append("Focus edits on these directories/patterns:\n")
+        for p in write_patterns:
+            sections.append(f"- `{p}`")
+        sections.append("")
+
+    # --- Allow: shell commands ---
+    allow_shell = allow.get("shell", {})
+    allowed_cmds: List[str] = []
+    if isinstance(allow_shell, dict):
+        for category in ("read", "execute", "remote"):
+            allowed_cmds.extend(_normalize_patterns(allow_shell.get(category)))
+    elif isinstance(allow_shell, list):
+        allowed_cmds.extend(allow_shell)
+    if allowed_cmds:
+        sections.append("### Allowed Commands\n")
+        for cmd in allowed_cmds:
+            sections.append(f"- `{cmd}`")
+        sections.append("")
+
+    # --- Deny ---
+    deny = permissions.get("deny", {})
+    deny_shell = deny.get("shell", [])
+    deny_cmds: List[str] = []
+    if isinstance(deny_shell, list):
+        deny_cmds.extend(deny_shell)
+    elif isinstance(deny_shell, dict):
+        for category in ("read", "execute", "remote"):
+            deny_cmds.extend(_normalize_patterns(deny_shell.get(category)))
+
+    deny_files = deny.get("files", {})
+    deny_write = _normalize_patterns(deny_files.get("write"))
+    deny_delete = _normalize_patterns(deny_files.get("delete"))
+
+    if deny_cmds or deny_write or deny_delete:
+        sections.append("### Never Do These\n")
+        for cmd in deny_cmds:
+            sections.append(f"- Never run: `{cmd}`")
+        for p in deny_write:
+            sections.append(f"- Never write to: `{p}`")
+        for p in deny_delete:
+            sections.append(f"- Never delete: `{p}`")
+        sections.append("")
+
+    # --- Confirm ---
+    confirm = permissions.get("confirm", {})
+    confirm_shell = confirm.get("shell", [])
+    confirm_actions = confirm.get("actions", [])
+    if confirm_shell or confirm_actions:
+        sections.append("### Ask Before Running\n")
+        for cmd in (confirm_shell if isinstance(confirm_shell, list) else []):
+            sections.append(f"- `{cmd}`")
+        for action in (confirm_actions if isinstance(confirm_actions, list) else []):
+            sections.append(f"- Action: {action}")
+        sections.append("")
+
+    # --- Resource limits ---
+    resource_limits = permissions.get("resource_limits", {})
+    if resource_limits:
+        sections.append("### Resource Limits\n")
+        for key, val in resource_limits.items():
+            sections.append(f"- {key}: {val}")
+        sections.append("")
+
+    if not sections:
+        return ""
+
+    return "\n## Permissions\n\n" + "\n".join(sections) + "\n"
+
+
+def _normalize_patterns(value: object) -> List[str]:
+    """Normalize a single pattern or list of patterns to a list."""
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, list):
+        return value
+    return []

aes/targets/claude.py

@@ -0,0 +1,153 @@
+"""Claude Code sync target."""
+
+from __future__ import annotations
+
+import json
+from typing import List
+
+from aes.targets._base import (
+    AES_SENTINEL_JSON_KEY,
+    AES_SENTINEL_MD,
+    AgentContext,
+    GeneratedFile,
+    SyncPlan,
+    SyncTarget,
+)
+from aes.targets._composer import (
+    compose_instructions_with_skill_index,
+    format_skill_permissions,
+    translate_permissions_to_claude,
+)
+
+
+class ClaudeTarget(SyncTarget):
+
+    @property
+    def name(self) -> str:
+        return "claude"
+
+    def plan(self, ctx: AgentContext, force: bool) -> SyncPlan:
+        plan = SyncPlan(target_name=self.name)
+
+        # 1. CLAUDE.md — with skill index (not inlined runbooks)
+        header = (
+            AES_SENTINEL_MD
+            + "\n# "
+            + ctx.manifest.get("name", "Project")
+            + " \u2014 Agent Instructions"
+        )
+        content = compose_instructions_with_skill_index(
+            project_name=ctx.manifest.get("name", "Project"),
+            instructions=ctx.instructions,
+            orchestrator=ctx.orchestrator,
+            skill_metadata=ctx.skill_metadata,
+            memory_project=ctx.memory_project,
+            header=header,
+            skill_runbooks=ctx.skill_runbooks,
+        )
+
+        if ctx.permissions:
+            confirm_section = _build_confirm_section(ctx.permissions)
+            if confirm_section:
+                content += "\n" + confirm_section
+
+        action = self._check_conflict(ctx.project_root, "CLAUDE.md", force)
+        plan.files.append(GeneratedFile(
+            relative_path="CLAUDE.md",
+            content=content,
+            description="Agent instructions for Claude Code",
+            action=action,
+        ))
+
+        # 2. .claude/settings.local.json
+        if ctx.permissions:
+            settings = translate_permissions_to_claude(ctx.permissions)
+            settings[AES_SENTINEL_JSON_KEY] = True
+            settings_json = json.dumps(settings, indent=2) + "\n"
+
+            action = self._check_conflict(
+                ctx.project_root, ".claude/settings.local.json", force
+            )
+            plan.files.append(GeneratedFile(
+                relative_path=".claude/settings.local.json",
+                content=settings_json,
+                description="Claude Code permissions",
+                action=action,
+            ))
+
+        # 3. .claude/commands/*.md (user-defined commands)
+        for cmd in ctx.commands:
+            rel_path = f".claude/commands/{cmd['id']}.md"
+            cmd_content = AES_SENTINEL_MD + "\n" + cmd.get("content", "")
+            action = self._check_conflict(ctx.project_root, rel_path, force)
+            plan.files.append(GeneratedFile(
+                relative_path=rel_path,
+                content=cmd_content,
+                description=f"Claude slash command: /{cmd['id']}",
+                action=action,
+            ))
+
+        # 4. .claude/commands/skills/<id>.md (skill runbooks as slash commands)
+        for skill_id, runbook in ctx.skill_runbooks.items():
+            rel_path = f".claude/commands/skills/{skill_id}.md"
+            skill_content = AES_SENTINEL_MD + "\n" + runbook
+
+            # Append per-skill metadata (negative triggers, permissions)
+            meta = ctx.skill_metadata.get(skill_id, {})
+            neg_triggers = meta.get("negative_triggers", [])
+            allowed_tools = meta.get("allowed_tools")
+
+            extras: List[str] = []
+            if neg_triggers:
+                extras.append("\n## Do NOT Use When\n")
+                for trigger in neg_triggers:
+                    extras.append(f"- {trigger}")
+            perms_section = format_skill_permissions(allowed_tools)
+            if perms_section:
+                extras.append(f"\n## Skill Permissions\n\n{perms_section}")
+            if extras:
+                skill_content += "\n" + "\n".join(extras) + "\n"
+
+            action = self._check_conflict(ctx.project_root, rel_path, force)
+            plan.files.append(GeneratedFile(
+                relative_path=rel_path,
+                content=skill_content,
+                description=f"Skill slash command: /skills/{skill_id}",
+                action=action,
+            ))
+
+        return plan
+
+
+def _build_confirm_section(permissions: dict) -> str:
+    """Build a markdown section listing actions that require confirmation."""
+    confirm = permissions.get("confirm", {})
+    if not confirm:
+        return ""
+
+    lines: List[str] = [
+        "\n## Actions Requiring Confirmation\n",
+        "Always ask for explicit user approval before:\n",
+    ]
+
+    for cmd in confirm.get("shell", []):
+        lines.append(f"- Running: `{cmd}`")
+
+    for action in confirm.get("actions", []):
+        lines.append(f"- Action: {action}")
+
+    confirm_files = confirm.get("files", {})
+    for p in _as_list(confirm_files.get("delete")):
+        lines.append(f"- Deleting files matching: `{p}`")
+
+    return "\n".join(lines) + "\n"
+
+
+def _as_list(value: object) -> list:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, list):
+        return value
+    return []

aes/targets/copilot.py

@@ -0,0 +1,48 @@
+"""GitHub Copilot sync target."""
+
+from __future__ import annotations
+
+from aes.targets._base import AES_SENTINEL_MD, AgentContext, GeneratedFile, SyncPlan, SyncTarget
+from aes.targets._composer import compose_instructions, translate_permissions_to_markdown
+
+
+class CopilotTarget(SyncTarget):
+
+    @property
+    def name(self) -> str:
+        return "copilot"
+
+    def plan(self, ctx: AgentContext, force: bool) -> SyncPlan:
+        plan = SyncPlan(target_name=self.name)
+
+        header = (
+            AES_SENTINEL_MD
+            + "\n# "
+            + ctx.manifest.get("name", "Project")
+            + " \u2014 Copilot Instructions"
+        )
+        content = compose_instructions(
+            project_name=ctx.manifest.get("name", "Project"),
+            instructions=ctx.instructions,
+            orchestrator=ctx.orchestrator,
+            skill_runbooks=ctx.skill_runbooks,
+            memory_project=ctx.memory_project,
+            header=header,
+        )
+
+        if ctx.permissions:
+            perms_md = translate_permissions_to_markdown(ctx.permissions)
+            if perms_md:
+                content += "\n" + perms_md
+
+        action = self._check_conflict(
+            ctx.project_root, ".github/copilot-instructions.md", force
+        )
+        plan.files.append(GeneratedFile(
+            relative_path=".github/copilot-instructions.md",
+            content=content,
+            description="GitHub Copilot instructions",
+            action=action,
+        ))
+
+        return plan

aes/targets/cursor.py

@@ -0,0 +1,46 @@
+"""Cursor sync target."""
+
+from __future__ import annotations
+
+from aes.targets._base import AES_SENTINEL_MD, AgentContext, GeneratedFile, SyncPlan, SyncTarget
+from aes.targets._composer import compose_instructions, translate_permissions_to_markdown
+
+
+class CursorTarget(SyncTarget):
+
+    @property
+    def name(self) -> str:
+        return "cursor"
+
+    def plan(self, ctx: AgentContext, force: bool) -> SyncPlan:
+        plan = SyncPlan(target_name=self.name)
+
+        header = (
+            AES_SENTINEL_MD
+            + "\n# "
+            + ctx.manifest.get("name", "Project")
+            + " \u2014 Cursor Rules"
+        )
+        content = compose_instructions(
+            project_name=ctx.manifest.get("name", "Project"),
+            instructions=ctx.instructions,
+            orchestrator=ctx.orchestrator,
+            skill_runbooks=ctx.skill_runbooks,
+            memory_project=ctx.memory_project,
+            header=header,
+        )
+
+        if ctx.permissions:
+            perms_md = translate_permissions_to_markdown(ctx.permissions)
+            if perms_md:
+                content += "\n" + perms_md
+
+        action = self._check_conflict(ctx.project_root, ".cursorrules", force)
+        plan.files.append(GeneratedFile(
+            relative_path=".cursorrules",
+            content=content,
+            description="Cursor rules file",
+            action=action,
+        ))
+
+        return plan