aes-cli 0.2.0__py3-none-any.whl

aes/commands/inspect.py

@@ -0,0 +1,204 @@
+"""aes inspect — Show project structure and stats."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+import yaml
+from rich.console import Console
+from rich.table import Table
+
+from aes.config import AGENT_DIR
+
+console = Console()
+
+
+def _load_yaml(path: Path) -> dict:
+    """Load YAML file, return empty dict on error."""
+    try:
+        with open(path) as f:
+            data = yaml.safe_load(f)
+        return data if isinstance(data, dict) else {}
+    except Exception:
+        return {}
+
+
+def _render_workflow_diagram(workflow: dict) -> str:
+    """Render a simple ASCII state diagram from a workflow definition."""
+    states = workflow.get("states", {})
+    transitions = workflow.get("transitions", [])
+
+    if not states or not transitions:
+        return "  (no states or transitions defined)"
+
+    lines = []
+    # Find initial and terminal states
+    initial = [s for s, v in states.items() if v.get("initial")]
+    terminal = [s for s, v in states.items() if v.get("terminal")]
+    intermediate = [s for s in states if s not in initial and s not in terminal]
+
+    # Render flow
+    all_ordered = initial + intermediate + terminal
+    if all_ordered:
+        # Build transition map
+        tx_map: dict[str, list[str]] = {}
+        for tx in transitions:
+            src = tx.get("from", "")
+            dst = tx.get("to", "")
+            tx_map.setdefault(src, []).append(dst)
+
+        # Show forward transitions
+        forward_chain = initial.copy()
+        visited = set(initial)
+        current = initial[0] if initial else ""
+        while current:
+            targets = tx_map.get(current, [])
+            next_state = None
+            for t in targets:
+                if t not in visited and t not in terminal:
+                    next_state = t
+                    break
+            if next_state:
+                forward_chain.append(next_state)
+                visited.add(next_state)
+                current = next_state
+            else:
+                break
+
+        lines.append("  " + " --> ".join(forward_chain))
+        if terminal:
+            lines.append("  Terminal: " + ", ".join(terminal))
+
+        # Show backward transitions
+        backward = [tx for tx in transitions if tx.get("to") in visited and
+                     all_ordered.index(tx.get("from", "")) > all_ordered.index(tx.get("to", ""))
+                     if tx.get("from", "") in all_ordered and tx.get("to", "") in all_ordered]
+        for tx in backward:
+            lines.append(f"  (loop) {tx['from']} --> {tx['to']}: {tx.get('description', 'reframe')}")
+
+    return "\n".join(lines) if lines else "  (could not render diagram)"
+
+
+@click.command("inspect")
+@click.argument("path", default=".", type=click.Path(exists=True))
+def inspect_cmd(path: str) -> None:
+    """Show AES project structure and statistics.
+
+    PATH is the project root directory (default: current directory).
+    """
+    project_root = Path(path).resolve()
+    agent_dir = project_root / AGENT_DIR
+
+    if not agent_dir.exists():
+        console.print(f"[red]Error:[/] No {AGENT_DIR}/ directory found at {project_root}")
+        raise SystemExit(1)
+
+    manifest_path = agent_dir / "agent.yaml"
+    if not manifest_path.exists():
+        console.print(f"[red]Error:[/] No agent.yaml found in {agent_dir}")
+        raise SystemExit(1)
+
+    manifest = _load_yaml(manifest_path)
+
+    # Header
+    console.print()
+    console.print(f"[bold]{manifest.get('name', 'unknown')}[/] v{manifest.get('version', '?')}")
+    console.print(f"  {manifest.get('description', '')}")
+    console.print(f"  Domain: {manifest.get('domain', 'unspecified')} | "
+                  f"Language: {manifest.get('runtime', {}).get('language', '?')} | "
+                  f"AES: {manifest.get('aes', '?')}")
+    console.print()
+
+    # Skills table
+    skills = manifest.get("skills", [])
+    if skills:
+        table = Table(title="Skills", show_header=True, header_style="bold")
+        table.add_column("ID", style="cyan")
+        table.add_column("Manifest")
+        table.add_column("Runbook")
+        table.add_column("Status")
+
+        for skill in skills:
+            manifest_exists = (agent_dir / skill.get("manifest", "")).exists() if skill.get("manifest") else False
+            runbook_exists = (agent_dir / skill.get("runbook", "")).exists() if skill.get("runbook") else False
+            status = "[green]OK[/]" if manifest_exists and runbook_exists else "[red]MISSING[/]"
+            table.add_row(
+                skill.get("id", "?"),
+                skill.get("manifest", "-"),
+                skill.get("runbook", "-"),
+                status,
+            )
+        console.print(table)
+        console.print()
+
+    # Registries
+    registries = manifest.get("registries", [])
+    if registries:
+        table = Table(title="Registries", show_header=True, header_style="bold")
+        table.add_column("ID", style="cyan")
+        table.add_column("Path")
+        table.add_column("Description")
+        table.add_column("Entries")
+
+        for reg in registries:
+            reg_path = agent_dir / reg["path"]
+            entry_count = "?"
+            if reg_path.exists():
+                reg_data = _load_yaml(reg_path)
+                categories = reg_data.get("categories", {})
+                count = sum(
+                    len(v) if isinstance(v, dict) else 0
+                    for v in categories.values()
+                )
+                entry_count = str(count)
+
+            table.add_row(
+                reg.get("id", "?"),
+                reg["path"],
+                reg.get("description", "-"),
+                entry_count,
+            )
+        console.print(table)
+        console.print()
+
+    # Workflows
+    workflows = manifest.get("workflows", [])
+    if workflows:
+        for wf_ref in workflows:
+            wf_path = agent_dir / wf_ref["path"]
+            if wf_path.exists():
+                wf_data = _load_yaml(wf_path)
+                n_states = len(wf_data.get("states", {}))
+                n_transitions = len(wf_data.get("transitions", []))
+                console.print(f"[bold]Workflow:[/] {wf_ref['id']} ({n_states} states, {n_transitions} transitions)")
+                console.print(_render_workflow_diagram(wf_data))
+                console.print()
+
+    # Commands
+    commands = manifest.get("commands", [])
+    if commands:
+        table = Table(title="Commands", show_header=True, header_style="bold")
+        table.add_column("Trigger", style="cyan")
+        table.add_column("Description")
+        for cmd in commands:
+            table.add_row(
+                cmd.get("trigger", f"/{cmd.get('id', '?')}"),
+                cmd.get("description", "-"),
+            )
+        console.print(table)
+        console.print()
+
+    # Summary
+    console.print("[bold]Summary[/]")
+    console.print(f"  Skills:     {len(skills)}")
+    console.print(f"  Registries: {len(registries)}")
+    console.print(f"  Workflows:  {len(workflows)}")
+    console.print(f"  Commands:   {len(commands)}")
+
+    # Resources
+    resources = manifest.get("resources", {})
+    if resources:
+        console.print(f"  CPU limit:  {resources.get('max_cpu_percent', '-')}%")
+        console.print(f"  Mem limit:  {resources.get('max_memory_percent', '-')}%")
+    console.print()

aes/commands/install.py

@@ -0,0 +1,379 @@
+"""aes install — Install skills from tarballs, local paths, registry, or agent.yaml deps."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tarfile
+import tempfile
+from pathlib import Path
+from typing import Optional, Tuple
+
+import click
+import yaml
+from rich.console import Console
+
+from aes.config import AGENT_DIR, MANIFEST_FILE, SKILLS_DIR, VENDOR_DIR
+from aes.registry import (
+    download_package,
+    fetch_index,
+    parse_registry_source,
+    resolve_version,
+)
+
+console = Console()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _find_skill_files(directory: Path) -> Tuple[str, str, Optional[str]]:
+    """Find skill manifest and runbook in a directory.
+
+    Returns (skill_id, manifest_filename, runbook_filename_or_None).
+
+    Handles two naming conventions:
+      - Named: ``deploy.skill.yaml`` + ``deploy.md``
+      - Generic: ``skill.yaml`` + ``runbook.md``
+    """
+    # Look for *.skill.yaml first (named convention), then skill.yaml (generic)
+    named = [p for p in directory.iterdir() if p.name.endswith(".skill.yaml") and p.name != "skill.yaml"]
+    generic = directory / "skill.yaml"
+
+    if named:
+        manifest_path = named[0]
+    elif generic.exists():
+        manifest_path = generic
+    else:
+        raise click.ClickException(
+            f"No skill manifest (*.skill.yaml) found in {directory}"
+        )
+
+    with open(manifest_path) as f:
+        manifest_data = yaml.safe_load(f) or {}
+
+    skill_id = manifest_data.get("id")
+    if not skill_id:
+        raise click.ClickException(
+            f"Skill manifest {manifest_path.name} is missing 'id' field"
+        )
+
+    # Determine runbook filename
+    runbook_name: Optional[str] = None
+    # Named convention: {id}.md
+    named_runbook = directory / f"{skill_id}.md"
+    generic_runbook = directory / "runbook.md"
+    if named_runbook.exists():
+        runbook_name = named_runbook.name
+    elif generic_runbook.exists():
+        runbook_name = generic_runbook.name
+
+    return skill_id, manifest_path.name, runbook_name
+
+
+def _place_in_vendor(
+    src_dir: Path,
+    skill_id: str,
+    project_root: Path,
+    force: bool,
+) -> Path:
+    """Copy a skill directory into ``.agent/skills/vendor/{id}/``.
+
+    Returns the destination path.  Raises if it already exists and *force*
+    is ``False``.
+    """
+    vendor_dir = project_root / AGENT_DIR / SKILLS_DIR / VENDOR_DIR / skill_id
+    if vendor_dir.exists():
+        if not force:
+            raise click.ClickException(
+                f"Skill '{skill_id}' already installed at {vendor_dir}. "
+                "Use --force to overwrite."
+            )
+        shutil.rmtree(vendor_dir)
+
+    shutil.copytree(src_dir, vendor_dir, symlinks=False)
+    return vendor_dir
+
+
+def _register_skill(
+    project_root: Path,
+    skill_id: str,
+    manifest_name: str,
+    runbook_name: Optional[str],
+) -> None:
+    """Ensure ``agent.yaml`` has an entry in ``skills:`` for *skill_id*.
+
+    Paths are relative to ``.agent/``, e.g.
+    ``skills/vendor/deploy/deploy.skill.yaml``.
+    """
+    manifest_path = project_root / AGENT_DIR / MANIFEST_FILE
+    with open(manifest_path) as f:
+        data = yaml.safe_load(f) or {}
+
+    skills = data.setdefault("skills", [])
+
+    # Build relative paths (relative to .agent/)
+    rel_manifest = f"{SKILLS_DIR}/{VENDOR_DIR}/{skill_id}/{manifest_name}"
+    rel_runbook = (
+        f"{SKILLS_DIR}/{VENDOR_DIR}/{skill_id}/{runbook_name}"
+        if runbook_name
+        else None
+    )
+
+    entry = {"id": skill_id, "manifest": rel_manifest}
+    if rel_runbook:
+        entry["runbook"] = rel_runbook
+
+    # Replace existing entry for this id, or append
+    replaced = False
+    for i, existing in enumerate(skills):
+        if existing.get("id") == skill_id:
+            skills[i] = entry
+            replaced = True
+            break
+    if not replaced:
+        skills.append(entry)
+
+    with open(manifest_path, "w") as f:
+        yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+
+
+def _safe_extract(tar: tarfile.TarFile, dest: Path) -> None:
+    """Extract tarball members, rejecting path-traversal attacks.
+
+    Safe for Python 3.9 (no ``data_filter`` yet).
+    """
+    for member in tar.getmembers():
+        member_path = os.path.normpath(member.name)
+        if member_path.startswith("..") or os.path.isabs(member_path):
+            raise click.ClickException(
+                f"Refusing to extract path-traversal entry: {member.name}"
+            )
+        # Extra safety: resolve and verify it stays under dest
+        target = (dest / member_path).resolve()
+        if not str(target).startswith(str(dest.resolve())):
+            raise click.ClickException(
+                f"Refusing to extract outside target: {member.name}"
+            )
+    tar.extractall(dest)
+
+
+# ---------------------------------------------------------------------------
+# Source detection
+# ---------------------------------------------------------------------------
+
+def _detect_source_type(source: str) -> str:
+    """Return one of: 'tarball', 'local', 'registry', 'git'."""
+    if source.startswith("local:"):
+        return "local"
+    if source.startswith("github:"):
+        return "git"
+    if source.startswith("aes-hub/"):
+        return "registry"
+    # Heuristic: file extension
+    if source.endswith(".tar.gz") or source.endswith(".tgz"):
+        return "tarball"
+    if Path(source).is_file() and tarfile.is_tarfile(source):
+        return "tarball"
+    if Path(source).is_dir():
+        return "local"
+    # If it looks like a path that doesn't exist, give a helpful error
+    return "unknown"
+
+
+# ---------------------------------------------------------------------------
+# Install modes
+# ---------------------------------------------------------------------------
+
+def _install_tarball(tarball_path: Path, project_root: Path, force: bool) -> str:
+    """Install a skill from a ``.tar.gz`` tarball.  Returns the skill id."""
+    if not tarball_path.exists():
+        raise click.ClickException(f"File not found: {tarball_path}")
+
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_dir = Path(tmp)
+        with tarfile.open(tarball_path, "r:gz") as tar:
+            _safe_extract(tar, tmp_dir)
+
+        # The tarball should contain a single top-level directory
+        children = [p for p in tmp_dir.iterdir() if p.is_dir()]
+        if len(children) == 1:
+            skill_dir = children[0]
+        else:
+            skill_dir = tmp_dir
+
+        skill_id, manifest_name, runbook_name = _find_skill_files(skill_dir)
+        _place_in_vendor(skill_dir, skill_id, project_root, force)
+        _register_skill(project_root, skill_id, manifest_name, runbook_name)
+
+    return skill_id
+
+
+def _install_local(source: str, project_root: Path, force: bool) -> str:
+    """Install a skill from a local directory.  Returns the skill id."""
+    # Strip ``local:`` prefix if present
+    dir_path = Path(source.removeprefix("local:")).resolve()
+    if not dir_path.is_dir():
+        raise click.ClickException(f"Directory not found: {dir_path}")
+
+    skill_id, manifest_name, runbook_name = _find_skill_files(dir_path)
+    _place_in_vendor(dir_path, skill_id, project_root, force)
+    _register_skill(project_root, skill_id, manifest_name, runbook_name)
+    return skill_id
+
+
+def _install_registry(source: str, project_root: Path, force: bool) -> str:
+    """Install a skill from the AES registry.  Returns the skill id."""
+    name, version_spec = parse_registry_source(source)
+
+    try:
+        index = fetch_index()
+    except Exception as exc:
+        raise click.ClickException(f"Failed to fetch registry index: {exc}")
+
+    packages = index.get("packages", {})
+    if name not in packages:
+        raise click.ClickException(
+            f"Package '{name}' not found in registry. "
+            "Use 'aes search' to find available packages."
+        )
+
+    pkg = packages[name]
+    available = list(pkg.get("versions", {}).keys())
+    version = resolve_version(version_spec, available)
+    if version is None:
+        raise click.ClickException(
+            f"No version of '{name}' matches '{version_spec}'. "
+            f"Available: {', '.join(available)}"
+        )
+
+    version_info = pkg["versions"][version]
+    sha256_expected = version_info["sha256"]
+
+    console.print(f"[dim]Downloading {name}@{version}...[/]")
+
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_dir = Path(tmp)
+        try:
+            tarball = download_package(name, version, sha256_expected, tmp_dir)
+        except Exception as exc:
+            raise click.ClickException(f"Failed to download {name}@{version}: {exc}")
+
+        return _install_tarball(tarball, project_root, force)
+
+
+def _install_from_deps(project_root: Path, force: bool) -> None:
+    """Install all dependencies declared in ``agent.yaml``."""
+    manifest_path = project_root / AGENT_DIR / MANIFEST_FILE
+    if not manifest_path.exists():
+        raise click.ClickException("No agent.yaml found")
+
+    with open(manifest_path) as f:
+        manifest = yaml.safe_load(f) or {}
+
+    deps = manifest.get("dependencies", {}).get("skills", {})
+    if not deps:
+        console.print("[dim]No skill dependencies declared in agent.yaml[/]")
+        return
+
+    installed = 0
+    skipped = 0
+    errored = 0
+
+    for name, source in deps.items():
+        source_type = _detect_source_type(source)
+        try:
+            if source_type == "local":
+                _install_local(source, project_root, force)
+                console.print(f"  [green]Installed:[/] {name} ← {source}")
+                installed += 1
+            elif source_type == "tarball":
+                _install_tarball(Path(source), project_root, force)
+                console.print(f"  [green]Installed:[/] {name} ← {source}")
+                installed += 1
+            elif source_type == "registry":
+                _install_registry(source, project_root, force)
+                console.print(f"  [green]Installed:[/] {name} ← {source}")
+                installed += 1
+            elif source_type == "git":
+                console.print(
+                    f"  [yellow]Skipped:[/] {name} — git sources not yet supported"
+                )
+                skipped += 1
+            else:
+                console.print(f"  [red]Error:[/] {name} — unknown source: {source}")
+                errored += 1
+        except click.ClickException as exc:
+            console.print(f"  [red]Error:[/] {name} — {exc.format_message()}")
+            errored += 1
+
+    console.print()
+    console.print(
+        f"[bold]Summary:[/] {installed} installed, {skipped} skipped, {errored} errored"
+    )
+
+
+# ---------------------------------------------------------------------------
+# CLI command
+# ---------------------------------------------------------------------------
+
+@click.command("install")
+@click.argument("source", required=False)
+@click.option(
+    "--path",
+    default=".",
+    type=click.Path(exists=True),
+    help="Project root directory",
+)
+@click.option(
+    "--force",
+    is_flag=True,
+    default=False,
+    help="Overwrite existing vendor skills",
+)
+def install_cmd(source: Optional[str], path: str, force: bool) -> None:
+    """Install skill dependencies.
+
+    If SOURCE is provided, install a specific skill from a tarball or local
+    directory.  Without SOURCE, install all dependencies from agent.yaml.
+
+    \b
+    Examples:
+      aes install ./deploy-1.0.0.tar.gz          # from tarball
+      aes install ../shared-skills/monitoring     # from local dir
+      aes install local:../shared-skills/deploy   # explicit local prefix
+      aes install                                 # all deps from agent.yaml
+    """
+    project_root = Path(path).resolve()
+    agent_dir = project_root / AGENT_DIR
+
+    if not agent_dir.exists():
+        console.print(f"[red]Error:[/] No {AGENT_DIR}/ directory found at {project_root}")
+        raise SystemExit(1)
+
+    if source is None:
+        _install_from_deps(project_root, force)
+        return
+
+    source_type = _detect_source_type(source)
+
+    if source_type == "tarball":
+        skill_id = _install_tarball(Path(source).resolve(), project_root, force)
+        console.print(f"[green]Installed skill:[/] {skill_id}")
+    elif source_type == "local":
+        skill_id = _install_local(source, project_root, force)
+        console.print(f"[green]Installed skill:[/] {skill_id}")
+    elif source_type == "registry":
+        skill_id = _install_registry(source, project_root, force)
+        console.print(f"[green]Installed skill:[/] {skill_id}")
+    elif source_type == "git":
+        console.print(
+            f"[yellow]Not yet supported:[/] git sources ({source})"
+        )
+        console.print("[dim]Only tarball, local, and registry install are available.[/]")
+    else:
+        raise click.ClickException(
+            f"Cannot determine source type for '{source}'. "
+            "Provide a .tar.gz file, a directory path, or use the local: prefix."
+        )