universal-agent-context 0.2.0__py3-none-any.whl

uacs/cli/memory.py

@@ -0,0 +1,142 @@
+"""CLI commands for memory management."""
+
+import os
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from uacs.memory.simple_memory import SimpleMemoryStore
+from uacs.cli.utils import get_project_root
+
+app = typer.Typer(help="Manage memory storage and queries")
+console = Console()
+
+
+def _get_store(project_root: Path | None = None) -> SimpleMemoryStore:
+    """Create a memory store for the current project."""
+    root = project_root or get_project_root()
+    global_override = os.environ.get("UACS_GLOBAL_MEMORY")
+    global_path = Path(global_override) if global_override else None
+    return SimpleMemoryStore(project_path=root, global_path=global_path)
+
+
+def _validate_scope(scope: str) -> str:
+    scope_normalized = scope.lower()
+    if scope_normalized not in {"project", "global", "both"}:
+        raise typer.BadParameter("Scope must be project, global, or both")
+    return scope_normalized
+
+
+@app.command("init")
+def init_memory(
+    scope: str = typer.Option(
+        "project",
+        "--scope",
+        "-s",
+        help="Scope to initialize: project, global, or both",
+    ),
+):
+    """Initialize simple JSON memory directories."""
+    scope_normalized = _validate_scope(scope)
+    store = _get_store()
+
+    initialized_paths = []
+    for current_scope in (
+        ["project", "global"] if scope_normalized == "both" else [scope_normalized]
+    ):
+        path = store.init_storage(current_scope)
+        initialized_paths.append(path)
+
+    for path in initialized_paths:
+        console.print(f"[green]✓[/green] Initialized memory at {path}")
+
+
+@app.command("stats")
+def memory_stats():
+    """Show memory statistics for project and global scopes."""
+    store = _get_store()
+    stats = store.get_stats()
+
+    table = Table(title="Memory Statistics")
+    table.add_column("Scope", style="cyan")
+    table.add_column("Entries", justify="right")
+    table.add_column("Size (KB)", justify="right")
+    table.add_column("Last Updated", justify="left")
+    table.add_column("Path", justify="left")
+
+    for scope in ("project", "global"):
+        scope_stats = stats.get(scope, {})
+        size_kb = scope_stats.get("size_bytes", 0) / 1024
+        table.add_row(
+            scope.capitalize(),
+            str(scope_stats.get("entries", 0)),
+            f"{size_kb:.1f}",
+            scope_stats.get("last_updated") or "—",
+            scope_stats.get("path", "—"),
+        )
+
+    console.print(table)
+
+
+@app.command("search")
+def search_memory(
+    query: str = typer.Argument(..., help="Query to search in memory entries"),
+    scope: str = typer.Option(
+        "both",
+        "--scope",
+        "-s",
+        help="Scope to search: project, global, or both",
+    ),
+):
+    """Search memory entries by substring match."""
+    scope_normalized = _validate_scope(scope)
+    store = _get_store()
+    results = store.search(query, scope=scope_normalized)
+
+    if not results:
+        console.print("[yellow]No results found[/yellow]")
+        return
+
+    for idx, entry in enumerate(results, start=1):
+        console.print(f"\n[bold]{idx}. {entry.key}[/bold] ({entry.scope})")
+        console.print(f"[dim]Created:[/dim] {entry.created_at}")
+        console.print(f"[dim]Updated:[/dim] {entry.updated_at}")
+        console.print_json(data=entry.data)
+
+
+@app.command("clean")
+def clean_memory(
+    scope: str = typer.Option(
+        "project",
+        "--scope",
+        "-s",
+        help="Scope to clean: project or global",
+    ),
+    older_than_days: int = typer.Option(
+        30,
+        "--older-than",
+        "-o",
+        help="Delete entries older than the given number of days",
+    ),
+):
+    """Delete old memory entries for the given scope."""
+    scope_normalized = _validate_scope(scope)
+    if scope_normalized == "both":
+        raise typer.BadParameter("Clean supports project or global scope only")
+
+    store = _get_store()
+    deleted = store.clean(older_than_days=older_than_days, scope=scope_normalized)
+
+    console.print(
+        f"[green]✓[/green] Deleted {deleted} entr{'y' if deleted == 1 else 'ies'} "
+        f"from {scope_normalized} memory older than {older_than_days} days"
+    )
+
+
+__all__ = ["app"]
+
+
+if __name__ == "__main__":
+    app()

uacs/cli/packages.py

@@ -0,0 +1,309 @@
+"""CLI commands for minimal package management.
+
+Inspired by GitHub CLI extensions pattern - simple, focused commands
+for installing packages from GitHub, Git URLs, or local paths.
+"""
+
+import typer
+from pathlib import Path
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from rich.table import Table
+
+from uacs.packages import PackageManager
+from uacs.cli.utils import get_project_root
+
+app = typer.Typer(help="Package management (GitHub CLI-style)")
+console = Console()
+
+
+def get_package_manager() -> PackageManager:
+    """Get PackageManager instance for current project."""
+    return PackageManager(get_project_root())
+
+
+@app.command("install")
+def install(
+    source: str = typer.Argument(
+        ...,
+        help="Package source: owner/repo, https://github.com/...git, or ./local/path",
+    ),
+    force: bool = typer.Option(
+        False, "--force", "-f", help="Overwrite if already installed"
+    ),
+    no_validate: bool = typer.Option(
+        False, "--no-validate", help="Skip validation after install"
+    ),
+):
+    """Install a package from GitHub, Git URL, or local path.
+
+    Examples:
+        uacs install owner/repo                     # GitHub repository
+        uacs install https://github.com/owner/repo.git  # Git URL
+        uacs install ./local/path                   # Local directory
+        uacs install owner/repo --force             # Overwrite existing
+        uacs install owner/repo --no-validate       # Skip validation
+    """
+    pm = get_package_manager()
+
+    try:
+        # Determine source type and display info
+        if source.startswith(("http://", "https://", "git@")):
+            console.print(f"[cyan]Installing from Git URL...[/cyan]")
+        elif source.startswith(("./", "../", "/")):
+            console.print(f"[cyan]Installing from local path...[/cyan]")
+        elif "/" in source:
+            console.print(f"[cyan]Installing {source} from GitHub...[/cyan]")
+        else:
+            console.print(
+                "[red]✗[/red] Invalid source format. Use: owner/repo, git URL, or ./path"
+            )
+            return
+
+        # Install with progress
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console,
+        ) as progress:
+            progress.add_task(description="Installing...", total=None)
+            package = pm.install(source, force=force, validate=not no_validate)
+
+        # Show success
+        console.print(f"[green]✓[/green] Successfully installed: [bold]{package.name}[/bold]")
+
+        # Display package info
+        table = Table(show_header=False, box=None, padding=(0, 2))
+        table.add_column("Field", style="dim")
+        table.add_column("Value")
+
+        table.add_row("Name", package.name)
+        table.add_row("Source", package.source)
+        table.add_row("Type", package.source_type.value)
+        if package.version:
+            table.add_row("Version", package.version)
+        if package.location:
+            table.add_row("Location", str(package.location))
+
+        console.print(table)
+
+        # Show validation warnings
+        if not package.is_valid:
+            console.print("\n[yellow]⚠[/yellow] Validation warnings:")
+            for error in package.validation_errors:
+                console.print(f"  • {error}")
+
+        console.print("\n[dim]List packages with: uacs list[/dim]")
+
+    except ValueError as e:
+        console.print(f"[red]✗[/red] {e}")
+    except Exception as e:
+        console.print(f"[red]✗[/red] Error installing package: {e}")
+
+
+@app.command("list")
+def list_packages(
+    show_invalid: bool = typer.Option(
+        False, "--show-invalid", help="Include invalid packages"
+    ),
+):
+    """List installed packages.
+
+    Examples:
+        uacs list                    # List all valid packages
+        uacs list --show-invalid     # Include invalid packages
+    """
+    pm = get_package_manager()
+
+    try:
+        packages = pm.list_installed()
+
+        if not packages:
+            console.print("[yellow]No packages installed[/yellow]")
+            console.print("\n[dim]Install with: uacs install owner/repo[/dim]")
+            return
+
+        # Create table
+        table = Table(
+            title="Installed Packages",
+            show_header=True,
+            header_style="bold cyan",
+        )
+
+        table.add_column("Name", style="cyan", width=25)
+        table.add_column("Source", style="green", width=35)
+        table.add_column("Type", style="magenta", width=10)
+        table.add_column("Version", style="blue", width=12)
+        table.add_column("Status", style="white", width=10)
+
+        for pkg in packages:
+            status = "[green]✓[/green]" if pkg.is_valid else "[red]✗[/red]"
+            version = pkg.version or "-"
+
+            table.add_row(
+                pkg.name,
+                pkg.source,
+                pkg.source_type.value,
+                version,
+                status,
+            )
+
+        console.print(table)
+        console.print(f"\n[dim]Total installed: {len(packages)}[/dim]")
+
+        # Show validation summary
+        invalid_count = sum(1 for p in packages if not p.is_valid)
+        if invalid_count > 0:
+            console.print(
+                f"[yellow]{invalid_count} package(s) have validation errors[/yellow]"
+            )
+            console.print("[dim]Use 'uacs validate <name>' for details[/dim]")
+
+    except Exception as e:
+        console.print(f"[red]✗[/red] Error listing packages: {e}")
+
+
+@app.command("validate")
+def validate_package(
+    package_name: str = typer.Argument(..., help="Package name to validate"),
+):
+    """Validate an installed package.
+
+    Examples:
+        uacs validate my-package     # Validate specific package
+    """
+    pm = get_package_manager()
+
+    try:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console,
+        ) as progress:
+            progress.add_task(description="Validating...", total=None)
+            is_valid, errors = pm.validate(package_name)
+
+        if is_valid:
+            console.print(
+                f"[green]✓[/green] Package '[bold]{package_name}[/bold]' is valid"
+            )
+        else:
+            console.print(
+                f"[red]✗[/red] Package '[bold]{package_name}[/bold]' has validation errors:"
+            )
+            for error in errors:
+                console.print(f"  • {error}")
+
+    except ValueError as e:
+        console.print(f"[red]✗[/red] {e}")
+    except Exception as e:
+        console.print(f"[red]✗[/red] Error validating package: {e}")
+
+
+@app.command("remove")
+def remove_package(
+    package_name: str = typer.Argument(..., help="Package name to remove"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+):
+    """Remove an installed package.
+
+    Examples:
+        uacs remove my-package       # Remove with confirmation
+        uacs remove my-package -y    # Remove without confirmation
+    """
+    pm = get_package_manager()
+
+    try:
+        # Get package info for confirmation
+        packages = pm.list_installed()
+        package = next((p for p in packages if p.name == package_name), None)
+
+        if not package:
+            console.print(f"[red]✗[/red] Package '{package_name}' not found")
+            console.print("\n[dim]List packages with: uacs list[/dim]")
+            return
+
+        # Show package info
+        console.print(f"\n[bold]Package: {package.name}[/bold]")
+        console.print(f"  Source: {package.source}")
+        console.print(f"  Type: {package.source_type.value}")
+        if package.location:
+            console.print(f"  Location: {package.location}")
+
+        # Confirm removal
+        if not yes:
+            confirm = typer.confirm(f"\nRemove '{package_name}'?")
+            if not confirm:
+                console.print("[yellow]Cancelled[/yellow]")
+                return
+
+        # Remove package
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console,
+        ) as progress:
+            progress.add_task(description="Removing...", total=None)
+            pm.remove(package_name)
+
+        console.print(f"[green]✓[/green] Removed '{package_name}'")
+
+    except ValueError as e:
+        console.print(f"[red]✗[/red] {e}")
+    except Exception as e:
+        console.print(f"[red]✗[/red] Error removing package: {e}")
+
+
+@app.command("update")
+def update_package(
+    package_name: str = typer.Argument(..., help="Package name to update"),
+):
+    """Update a package to the latest version.
+
+    Examples:
+        uacs update my-package       # Update to latest version
+    """
+    pm = get_package_manager()
+
+    try:
+        # Get current package info
+        packages = pm.list_installed()
+        package = next((p for p in packages if p.name == package_name), None)
+
+        if not package:
+            console.print(f"[red]✗[/red] Package '{package_name}' not found")
+            console.print("\n[dim]List packages with: uacs list[/dim]")
+            return
+
+        console.print(f"[cyan]Updating {package_name}...[/cyan]")
+        console.print(f"  Current source: {package.source}")
+
+        # Update with progress
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console,
+        ) as progress:
+            progress.add_task(description="Updating...", total=None)
+            updated_package = pm.update(package_name)
+
+        # Show success
+        console.print(
+            f"[green]✓[/green] Successfully updated: [bold]{updated_package.name}[/bold]"
+        )
+
+        # Display version info if available
+        if updated_package.version:
+            console.print(f"  Version: {updated_package.version}")
+
+    except ValueError as e:
+        console.print(f"[red]✗[/red] {e}")
+    except Exception as e:
+        console.print(f"[red]✗[/red] Error updating package: {e}")
+
+
+__all__ = ["app"]
+
+
+if __name__ == "__main__":
+    app()

uacs/cli/skills.py

@@ -0,0 +1,144 @@
+"""CLI commands for managing agent skills."""
+
+import json
+from pathlib import Path
+
+import typer
+import yaml
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.table import Table
+
+from uacs import UACS
+from uacs.adapters import FormatAdapterRegistry
+from uacs.adapters.agent_skill_adapter import AgentSkillAdapter
+from uacs.skills_validator import SkillValidator
+from uacs.cli.utils import get_project_root
+
+app = typer.Typer(help="Manage agent skills")
+console = Console()
+
+
+def get_uacs() -> UACS:
+    """Get UACS instance for current project."""
+    return UACS(get_project_root())
+
+
+@app.command()
+def validate(
+    skill_path: Path = typer.Argument(..., help="Path to skill directory"),
+    strict: bool = typer.Option(False, "--strict", help="Fail on warnings"),
+):
+    """Validate a skill against the Agent Skills specification."""
+    result = SkillValidator.validate_file(skill_path)
+
+    if result.valid:
+        if strict and result.warnings:
+            console.print(f"[red]✗[/red] Skill at {skill_path} has warnings (strict mode)")
+            for warning in result.warnings:
+                console.print(f"  - {warning.field}: {warning.message}")
+            raise typer.Exit(code=1)
+
+        console.print(f"[green]✓[/green] Skill at {skill_path} is valid")
+        for warning in result.warnings:
+            console.print(f"  [yellow]![/yellow] {warning.field}: {warning.message}")
+    else:
+        console.print(f"[red]✗[/red] Skill at {skill_path} is invalid")
+        for error in result.errors:
+            console.print(f"  - {error.field}: {error.message}")
+        raise typer.Exit(code=1)
+
+
+@app.command("read-properties")
+def read_properties(
+    skill_path: Path = typer.Argument(..., help="Path to skill directory"),
+    output_format: str = typer.Option("json", "--format", "-f", help="Output format (json/yaml)"),
+):
+    """Read skill properties (frontmatter)."""
+    skill_file = skill_path / "SKILL.md"
+    if not skill_file.exists():
+        console.print(f"[red]✗[/red] SKILL.md not found in {skill_path}")
+        raise typer.Exit(code=1)
+
+    content = skill_file.read_text()
+    frontmatter, _, errors = SkillValidator.extract_frontmatter(content)
+
+    if errors:
+        console.print(f"[red]✗[/red] Failed to parse frontmatter")
+        for error in errors:
+            console.print(f"  - {error.message}")
+        raise typer.Exit(code=1)
+
+    if output_format == "json":
+        print(json.dumps(frontmatter, indent=2))
+    elif output_format == "yaml":
+        print(yaml.dump(frontmatter))
+    else:
+        console.print(f"[red]✗[/red] Unknown format: {output_format}")
+        raise typer.Exit(code=1)
+
+
+@app.command("to-prompt")
+def to_prompt(
+    skill_paths: list[Path] = typer.Argument(..., help="Paths to skill directories"),
+):
+    """Convert skills to prompt format."""
+    adapter = AgentSkillAdapter()
+    prompts = []
+
+    for path in skill_paths:
+        skill_file = path / "SKILL.md"
+        if not skill_file.exists():
+            console.print(f"[red]✗[/red] SKILL.md not found in {path}")
+            raise typer.Exit(code=1)
+
+        content = skill_file.read_text()
+        adapter.parsed = adapter.parse(content)
+        prompts.append(adapter.to_system_prompt())
+
+    print("\n\n".join(prompts))
+
+
+@app.command()
+def list(
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
+):
+    """List all available skills in the project."""
+    uacs = get_uacs()
+    skills = uacs.get_capabilities()
+
+    if json_output:
+        print(json.dumps(skills, indent=2))
+        return
+
+    table = Table(title="Available Skills")
+    table.add_column("Name", style="cyan")
+    table.add_column("Origin", style="yellow", width=40)
+    table.add_column("Source", style="green")
+    table.add_column("Description")
+
+    for skill in skills.get("agent_skills", []):
+        source_path = skill.get("source", "unknown")
+        skill_name = skill.get("name", "unknown")
+
+        # Check if skill was installed via package manager
+        try:
+            installed_packages = uacs.list_packages()
+            package = next((p for p in installed_packages if p.name == skill_name), None)
+            if package:
+                origin = package.source  # e.g., "owner/repo" or "local"
+            else:
+                origin = "local"
+        except Exception:
+            origin = "local"
+
+        table.add_row(
+            skill_name,
+            origin,
+            source_path,
+            skill.get("description", "")[:100]
+        )
+
+    console.print(table)
+

uacs/cli/utils.py

@@ -0,0 +1,24 @@
+"""Shared CLI utilities for UACS commands."""
+
+import os
+from pathlib import Path
+
+
+def get_project_root() -> Path:
+    """Get the effective project root directory.
+
+    Prioritizes PWD environment variable to handle cases where the tool
+    is invoked via 'uv run --directory ...' which changes the process CWD.
+    """
+    # Check if PWD is set and valid
+    pwd = os.environ.get("PWD")
+    if pwd:
+        path = Path(pwd)
+        if path.exists() and path.is_dir():
+            return path
+
+    # Fallback to current working directory
+    return Path.cwd()
+
+
+__all__ = ["get_project_root"]

uacs/config/repositories.yaml

@@ -0,0 +1,26 @@
+repositories:
+  - owner: modelcontextprotocol
+    repo: servers
+    type: mcp
+    path: src
+    description: Official Model Context Protocol servers
+  - owner: agentskills
+    repo: agentskills
+    type: skill
+    path: skills-ref
+    description: Agent Skills reference implementations
+  - owner: ComposioHQ
+    repo: awesome-claude-skills
+    type: skill
+    path: ""
+    description: Curated collection of Claude skills
+  - owner: huggingface
+    repo: skills
+    type: skill
+    path: ""
+    description: Hugging Face Agent Skills
+  - owner: anthropics
+    repo: skills
+    type: skill
+    path: skills
+    description: Anthropic Official Skills