aes-cli 0.2.0__py3-none-any.whl

aes/mcp_server.py

@@ -0,0 +1,213 @@
+"""AES MCP Server — Model Context Protocol server for the AES registry."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import sys
+from pathlib import Path
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from aes.config import AGENT_DIR
+from aes.registry import fetch_index, search_packages
+from aes.validator import validate_agent_dir
+
+# Logging must go to stderr — stdout is the JSON-RPC channel
+logging.basicConfig(level=logging.INFO, stream=sys.stderr)
+logger = logging.getLogger("aes-mcp")
+
+mcp = FastMCP("aes-registry")
+
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+def aes_search(
+    query: str = "",
+    tag: str = "",
+    domain: str = "",
+    pkg_type: str = "",
+) -> str:
+    """Search the AES package registry for skills and templates.
+
+    Args:
+        query: Keyword to search package names and descriptions.
+        tag: Filter by tag (e.g. "ml", "devops").
+        domain: Filter by domain (convention: domain as tag).
+        pkg_type: Filter by type: "skill" or "template".
+
+    Returns a JSON array of matching packages.
+    """
+    try:
+        results = search_packages(
+            query=query or "",
+            tag=tag or None,
+            domain=domain or None,
+            pkg_type=pkg_type or None,
+        )
+        return json.dumps(results, indent=2)
+    except Exception as exc:
+        return json.dumps({"error": f"Registry search failed: {exc}"})
+
+
+@mcp.tool()
+def aes_inspect(name: str) -> str:
+    """Show details about a specific package in the AES registry.
+
+    Returns all versions, description, tags, and metadata for the package.
+
+    Args:
+        name: Package name to inspect.
+    """
+    try:
+        index = fetch_index()
+    except Exception as exc:
+        return json.dumps({"error": f"Failed to fetch registry index: {exc}"})
+
+    packages = index.get("packages", {})
+    if name not in packages:
+        return json.dumps({"error": f"Package '{name}' not found in registry."})
+
+    pkg = packages[name]
+    return json.dumps(
+        {
+            "name": name,
+            "type": pkg.get("type", "skill"),
+            "description": pkg.get("description", ""),
+            "tags": pkg.get("tags", []),
+            "latest": pkg.get("latest", ""),
+            "versions": pkg.get("versions", {}),
+        },
+        indent=2,
+    )
+
+
+@mcp.tool()
+def aes_install(
+    source: str,
+    project_path: str = ".",
+    force: bool = False,
+) -> str:
+    """Install a skill or template from the AES registry into the project.
+
+    Installs into the .agent/skills/vendor/ directory and registers in agent.yaml.
+
+    Args:
+        source: Package source — registry ref (e.g. "aes-hub/deploy@^1.0"),
+                local path, or tarball path.
+        project_path: Project root directory (defaults to current directory).
+        force: Overwrite existing vendor skills if True.
+    """
+    import click
+
+    from aes.commands.install import (
+        _detect_source_type,
+        _install_local,
+        _install_registry,
+        _install_tarball,
+    )
+
+    project_root = Path(project_path).resolve()
+    agent_dir = project_root / AGENT_DIR
+
+    if not agent_dir.exists():
+        return json.dumps(
+            {"error": f"No {AGENT_DIR}/ directory found at {project_root}"}
+        )
+
+    source_type = _detect_source_type(source)
+
+    if source_type == "git":
+        return json.dumps({"error": "Git sources are not yet supported."})
+    if source_type == "unknown":
+        return json.dumps(
+            {"error": f"Cannot determine source type for '{source}'."}
+        )
+
+    try:
+        # Redirect stdout to stderr so rich.console.print doesn't corrupt
+        # the stdio JSON-RPC channel.
+        with contextlib.redirect_stdout(sys.stderr):
+            if source_type == "registry":
+                skill_id = _install_registry(source, project_root, force)
+            elif source_type == "tarball":
+                skill_id = _install_tarball(
+                    Path(source).resolve(), project_root, force
+                )
+            elif source_type == "local":
+                skill_id = _install_local(source, project_root, force)
+            else:
+                return json.dumps({"error": f"Unsupported source type: {source_type}"})
+
+        return json.dumps(
+            {
+                "installed": skill_id,
+                "vendor_path": f".agent/skills/vendor/{skill_id}",
+            }
+        )
+    except click.ClickException as exc:
+        return json.dumps({"error": exc.format_message()})
+    except Exception as exc:
+        return json.dumps({"error": str(exc)})
+
+
+@mcp.tool()
+def aes_validate(project_path: str = ".") -> str:
+    """Validate the .agent/ directory against AES schemas.
+
+    Reports pass/fail for each file and any validation errors.
+
+    Args:
+        project_path: Project root directory (defaults to current directory).
+    """
+    project_root = Path(project_path).resolve()
+    agent_dir = project_root / AGENT_DIR
+
+    if not agent_dir.exists():
+        return json.dumps(
+            {"error": f"No {AGENT_DIR}/ directory found at {project_root}"}
+        )
+
+    try:
+        results = validate_agent_dir(agent_dir)
+    except Exception as exc:
+        return json.dumps({"error": f"Validation failed: {exc}"})
+
+    passed = sum(1 for r in results if r.valid)
+    failed = sum(1 for r in results if not r.valid)
+
+    return json.dumps(
+        {
+            "summary": {"passed": passed, "failed": failed, "total": len(results)},
+            "results": [
+                {
+                    "file": str(r.file_path),
+                    "schema": r.schema_type,
+                    "valid": r.valid,
+                    "errors": r.errors,
+                }
+                for r in results
+            ],
+        },
+        indent=2,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    """Run the AES MCP server over stdio."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

aes/registry.py

@@ -0,0 +1,294 @@
+"""Registry client — fetch index, resolve versions, download packages."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import urllib.request
+import urllib.error
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+# Default registry URL (R2/S3 public bucket)
+REGISTRY_URL = os.environ.get("AES_REGISTRY_URL", "https://registry.aes-official.com")
+INDEX_PATH = "index.json"
+PACKAGES_PATH = "packages"
+
+
+def _parse_version(v: str) -> Tuple[int, int, int]:
+    """Parse a semver string into (major, minor, patch)."""
+    match = re.match(r"^(\d+)\.(\d+)\.(\d+)", v)
+    if not match:
+        raise ValueError(f"Invalid semver: {v}")
+    return int(match.group(1)), int(match.group(2)), int(match.group(3))
+
+
+def _version_matches(version: str, spec: str) -> bool:
+    """Check if *version* satisfies *spec*.
+
+    Supports: exact "1.2.3", caret "^1.2.0", tilde "~1.2.0",
+    minimum ">=1.0.0", wildcard "*".
+    """
+    if spec == "*":
+        return True
+
+    ver = _parse_version(version)
+
+    if spec.startswith("^"):
+        base = _parse_version(spec[1:])
+        # >=base, <next_major (or <next_minor if major==0)
+        if base[0] == 0:
+            ceiling = (0, base[1] + 1, 0)
+        else:
+            ceiling = (base[0] + 1, 0, 0)
+        return base <= ver < ceiling
+
+    if spec.startswith("~"):
+        base = _parse_version(spec[1:])
+        ceiling = (base[0], base[1] + 1, 0)
+        return base <= ver < ceiling
+
+    if spec.startswith(">="):
+        base = _parse_version(spec[2:])
+        return ver >= base
+
+    if spec.startswith(">"):
+        base = _parse_version(spec[1:])
+        return ver > base
+
+    if spec.startswith("<="):
+        base = _parse_version(spec[2:])
+        return ver <= base
+
+    if spec.startswith("<"):
+        base = _parse_version(spec[1:])
+        return ver < base
+
+    # Exact match
+    return ver == _parse_version(spec)
+
+
+def resolve_version(spec: str, available: List[str]) -> Optional[str]:
+    """Find the best (highest) version matching *spec*."""
+    matches = [v for v in available if _version_matches(v, spec)]
+    if not matches:
+        return None
+    matches.sort(key=_parse_version)
+    return matches[-1]
+
+
+_NAME_RE = re.compile(r"^[a-z][a-z0-9_-]{0,63}$")
+
+
+def parse_registry_source(source: str) -> Tuple[str, str]:
+    """Parse ``aes-hub/deploy@^1.2.0`` into (name, version_spec).
+
+    Returns (name, "*") if no version constraint given.
+    Raises ValueError if name is invalid.
+    """
+    # Strip prefix
+    name_ver = source
+    if "/" in name_ver:
+        name_ver = name_ver.split("/", 1)[1]
+
+    if "@" in name_ver:
+        name, version_spec = name_ver.split("@", 1)
+    else:
+        name = name_ver
+        version_spec = "*"
+
+    if not _NAME_RE.match(name):
+        raise ValueError(
+            f"Invalid package name {name!r}: must be 1-64 lowercase chars "
+            "starting with a letter (a-z, 0-9, _, -)"
+        )
+
+    return name, version_spec
+
+
+def fetch_index(registry_url: Optional[str] = None) -> dict:
+    """Fetch and parse the registry ``index.json``."""
+    base = registry_url or os.environ.get("AES_REGISTRY_URL", REGISTRY_URL)
+    url = f"{base.rstrip('/')}/{INDEX_PATH}"
+
+    req = urllib.request.Request(url)
+    token = os.environ.get("AES_REGISTRY_KEY")
+    if token:
+        req.add_header("Authorization", f"Bearer {token}")
+
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        return json.loads(resp.read().decode())
+
+
+def download_package(
+    name: str,
+    version: str,
+    sha256_expected: str,
+    dest: Path,
+    registry_url: Optional[str] = None,
+) -> Path:
+    """Download a tarball from the registry and verify its sha256.
+
+    Returns the local path to the downloaded file.
+    """
+    base = registry_url or os.environ.get("AES_REGISTRY_URL", REGISTRY_URL)
+    url = f"{base.rstrip('/')}/{PACKAGES_PATH}/{name}/{version}.tar.gz"
+
+    tarball_path = dest / f"{name}-{version}.tar.gz"
+
+    req = urllib.request.Request(url)
+    token = os.environ.get("AES_REGISTRY_KEY")
+    if token:
+        req.add_header("Authorization", f"Bearer {token}")
+
+    with urllib.request.urlopen(req, timeout=120) as resp:
+        data = resp.read()
+
+    actual_sha = hashlib.sha256(data).hexdigest()
+    if actual_sha != sha256_expected:
+        raise ValueError(
+            f"SHA256 mismatch for {name}@{version}: "
+            f"expected {sha256_expected[:16]}..., got {actual_sha[:16]}..."
+        )
+
+    tarball_path.write_bytes(data)
+    return tarball_path
+
+
+def upload_package(
+    tarball_path: Path,
+    name: str,
+    version: str,
+    description: str,
+    tags: Optional[List[str]] = None,
+    registry_url: Optional[str] = None,
+    pkg_type: str = "skill",
+    visibility: str = "public",
+) -> dict:
+    """Upload a tarball and update the registry index.
+
+    Returns the updated index entry for this package.
+    """
+    base = registry_url or os.environ.get("AES_REGISTRY_URL", REGISTRY_URL)
+    token = os.environ.get("AES_REGISTRY_KEY")
+    if not token:
+        raise RuntimeError(
+            "AES_REGISTRY_KEY environment variable is required for publishing. "
+            "Set it to your registry API token."
+        )
+
+    tarball_data = tarball_path.read_bytes()
+    sha = hashlib.sha256(tarball_data).hexdigest()
+
+    # Upload tarball
+    upload_url = f"{base.rstrip('/')}/{PACKAGES_PATH}/{name}/{version}.tar.gz"
+    req = urllib.request.Request(upload_url, data=tarball_data, method="PUT")
+    req.add_header("Authorization", f"Bearer {token}")
+    req.add_header("Content-Type", "application/gzip")
+    try:
+        urllib.request.urlopen(req, timeout=120)
+    except urllib.error.HTTPError as exc:
+        if exc.code == 409:
+            raise RuntimeError(
+                f"Version {version} of '{name}' already exists in the registry. "
+                "Bump the version in your skill manifest and try again."
+            ) from None
+        raise
+
+    # Fetch current index
+    try:
+        index = fetch_index(registry_url)
+    except (urllib.error.URLError, urllib.error.HTTPError):
+        index = {"packages": {}}
+
+    # Update index
+    packages = index.setdefault("packages", {})
+    pkg = packages.setdefault(name, {
+        "description": description,
+        "latest": version,
+        "versions": {},
+    })
+    pkg["description"] = description
+    pkg["type"] = pkg_type
+    pkg["visibility"] = visibility
+    if tags:
+        pkg["tags"] = tags
+
+    from datetime import datetime, timezone
+    pkg["versions"][version] = {
+        "url": f"{PACKAGES_PATH}/{name}/{version}.tar.gz",
+        "sha256": sha,
+        "published_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+    # Update "latest" if this version is higher
+    try:
+        if _parse_version(version) >= _parse_version(pkg.get("latest", "0.0.0")):
+            pkg["latest"] = version
+    except ValueError:
+        pkg["latest"] = version
+
+    # Upload updated index
+    index_data = json.dumps(index, indent=2).encode()
+    index_url = f"{base.rstrip('/')}/{INDEX_PATH}"
+    req = urllib.request.Request(index_url, data=index_data, method="PUT")
+    req.add_header("Authorization", f"Bearer {token}")
+    req.add_header("Content-Type", "application/json")
+    urllib.request.urlopen(req, timeout=30)
+
+    return pkg
+
+
+def search_packages(
+    query: str = "",
+    tag: Optional[str] = None,
+    domain: Optional[str] = None,
+    index: Optional[dict] = None,
+    registry_url: Optional[str] = None,
+    pkg_type: Optional[str] = None,
+) -> List[Dict[str, object]]:
+    """Search the registry index for matching packages.
+
+    Returns list of dicts with: name, description, latest, tags, type.
+    """
+    if index is None:
+        index = fetch_index(registry_url)
+
+    results = []
+    for name, pkg in index.get("packages", {}).items():
+        # Type filter (packages without type default to "skill")
+        if pkg_type:
+            if pkg.get("type", "skill") != pkg_type:
+                continue
+
+        # Keyword filter
+        if query:
+            q = query.lower()
+            haystack = f"{name} {pkg.get('description', '')}".lower()
+            if q not in haystack:
+                continue
+
+        # Tag filter
+        if tag:
+            pkg_tags = pkg.get("tags", [])
+            if tag.lower() not in [t.lower() for t in pkg_tags]:
+                continue
+
+        # Domain filter (convention: domain is a tag)
+        if domain:
+            pkg_tags = pkg.get("tags", [])
+            if domain.lower() not in [t.lower() for t in pkg_tags]:
+                continue
+
+        results.append({
+            "name": name,
+            "description": pkg.get("description", ""),
+            "latest": pkg.get("latest", "?"),
+            "tags": pkg.get("tags", []),
+            "type": pkg.get("type", "skill"),
+            "versions": list(pkg.get("versions", {}).keys()),
+        })
+
+    return results

aes/scaffold/agent.yaml.jinja

@@ -0,0 +1,135 @@
+{% if domain_config %}
+# .agent/agent.yaml — AES Manifest
+aes: "1.0"
+
+name: "{{ name }}"
+version: "0.1.0"
+description: "{{ domain_config.instructions_description or 'TODO: describe what this agentic system does' }}"
+domain: "{{ domain }}"
+license: "MIT"
+
+runtime:
+  language: "{{ language }}"
+
+agent:
+  instructions: "instructions.md"
+  permissions: "permissions.yaml"
+{% if has_skills %}
+  orchestrator: "skills/ORCHESTRATOR.md"
+{% if domain_config.skills %}
+
+skills:
+{% for skill in domain_config.skills %}
+  - id: "{{ skill.id }}"
+    manifest: "skills/{{ skill.id }}.skill.yaml"
+    runbook: "skills/{{ skill.id }}.md"
+{% endfor %}
+{% else %}
+
+skills: []
+{% endif %}
+{% endif %}
+{% if has_workflows and domain_config.workflow %}
+
+workflows:
+  - id: "{{ domain_config.workflow.id }}"
+    path: "workflows/{{ domain_config.workflow.id }}.yaml"
+{% endif %}
+
+commands:
+  - id: "setup"
+    path: "commands/setup.md"
+    trigger: "/setup"
+    description: "Review and customize .agent/ files for your project"
+{% if domain_config.workflow_commands %}
+{% for cmd in domain_config.workflow_commands %}
+  - id: "{{ cmd.id }}"
+    path: "commands/{{ cmd.id }}.md"
+    trigger: "{{ cmd.trigger }}"
+    description: "{{ cmd.description }}"
+{% endfor %}
+{% endif %}
+
+environment:
+{% if domain_config.env_required %}
+  required:
+{% for env in domain_config.env_required %}
+    - name: "{{ env.name }}"
+      description: "{{ env.description }}"
+{% endfor %}
+{% else %}
+  required: []
+{% endif %}
+{% if domain_config.env_optional %}
+  optional:
+{% for env in domain_config.env_optional %}
+    - name: "{{ env.name }}"
+      default: "{{ env.default }}"
+      description: "{{ env.description }}"
+{% endfor %}
+{% else %}
+  optional: []
+{% endif %}
+{% else %}
+# .agent/agent.yaml — AES Manifest
+aes: "1.0"
+
+name: "{{ name }}"
+version: "0.1.0"
+# <!-- AGENT: Describe what this agentic system does in one sentence.
+#      If code exists: read README + entry point + package config.
+#      If greenfield: ask the user what they're building. -->
+description: "TODO: describe what this agentic system does"
+domain: "{{ domain }}"
+license: "MIT"
+
+runtime:
+  language: "{{ language }}"
+
+agent:
+  instructions: "instructions.md"
+  permissions: "permissions.yaml"
+{% if has_skills %}
+  orchestrator: "skills/ORCHESTRATOR.md"
+
+skills: []
+  # - id: "example"
+  #   manifest: "skills/example.skill.yaml"
+  #   runbook: "skills/example.md"
+{% endif %}
+{% if has_registry %}
+
+registries: []
+  # - id: "components"
+  #   path: "registry/components.yaml"
+  #   description: "Component definitions"
+{% endif %}
+{% if has_workflows %}
+
+workflows: []
+  # - id: "pipeline"
+  #   path: "workflows/pipeline.yaml"
+{% endif %}
+
+commands:
+  - id: "setup"
+    path: "commands/setup.md"
+    trigger: "/setup"
+    description: "Populate .agent/ files by analyzing the codebase"
+  # - id: "run"
+  #   path: "commands/run.md"
+  #   trigger: "/run"
+  #   description: "Run the main workflow"
+
+environment:
+  # <!-- AGENT: List required and optional environment variables.
+  #      If code exists: scan for os.environ, process.env, .env, .env.example.
+  #      If greenfield: ask "any API keys or config vars needed?" -->
+  required: []
+    # - name: "API_KEY"
+    #   description: "Main API key"
+  optional: []
+    # - name: "TIMEOUT"
+    #   default: "300"
+    #   description: "Operation timeout"
+{% endif %}

aes/scaffold/agentignore.jinja

@@ -0,0 +1,61 @@
+# .agentignore — Files agents should never read or modify
+
+# Secrets
+.env
+.env.*
+*.pem
+*.key
+*.p12
+credentials.json
+
+# Databases
+*.sqlite3
+*.db
+
+# Binary artifacts
+{% if language == "python" %}
+*.joblib
+*.pkl
+*.h5
+*.pt
+{% elif language == "javascript" or language == "typescript" %}
+*.wasm
+{% endif %}
+
+# Large data
+data/**/*.parquet
+data/**/*.csv
+
+# Build artifacts
+{% if language == "python" %}
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+.venv/
+{% elif language == "javascript" or language == "typescript" %}
+node_modules/
+dist/
+.next/
+{% elif language == "go" %}
+vendor/
+{% elif language == "rust" %}
+target/
+{% elif language == "java" %}
+target/
+build/
+*.class
+*.jar
+{% endif %}
+
+# System
+.git/
+.DS_Store
+Thumbs.db
+
+# Agent session data
+.agent/memory/sessions/
+
+# Local config (not committed)
+.agent/local.yaml