agent-context-mcp 0.3.0__py3-none-any.whl

acp/__init__.py

@@ -0,0 +1,3 @@
+"""acp — Python package manager and MCP server for Agent Context Protocol projects."""
+
+__version__ = "0.3.0"

acp/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI entry points."""

acp/cli/init.py

@@ -0,0 +1,222 @@
+"""acp init — bootstrap a new ACP project.
+
+Fetches templates from agent-context-protocol (GitHub) at runtime via a
+shallow git clone. Templates are not bundled with the wheel; this means
+templates can evolve independently of acp-mcp release cadence.
+
+Requires: git on PATH.
+"""
+from __future__ import annotations
+
+import re
+import shutil
+from datetime import date
+from pathlib import Path
+
+import typer
+import yaml
+from rich.console import Console
+from rich.text import Text
+
+from acp.core.fetch import fetch_acp_templates
+
+console = Console()
+
+app = typer.Typer(
+    help="Bootstrap a new ACP project.",
+    no_args_is_help=False,
+)
+
+# Directories inside agent/ to skip entirely when copying from a clone.
+_SKIP_AGENT_SUBDIRS = frozenset({
+    "reports",
+    "clarifications",
+    "feedback",
+    "drafts",
+    "projects",
+    "scripts",
+})
+
+# Directories inside agent/ where we copy ONLY *.template.* files
+# (not project-specific instances the source repo might have).
+_TEMPLATE_ONLY_SUBDIRS = frozenset({
+    "design",
+    "milestones",
+    "tasks",
+    "patterns",
+    "specs",
+    "artifacts",
+    "sessions",
+})
+
+
+def _should_copy(rel: Path) -> bool:
+    """Return True if this path from the clone root should be copied to the target.
+
+    rel is relative to the clone root (e.g. "agent/commands/acp.proceed.md").
+    """
+    parts = rel.parts
+
+    # Skip .git, .github, and other hidden top-level dirs
+    if parts[0].startswith("."):
+        return False
+
+    # At top level: only AGENT.md and .gitignore are meaningful for new projects
+    if len(parts) == 1:
+        return parts[0] in ("AGENT.md", ".gitignore")
+
+    # Inside agent/: apply subdirectory rules
+    if parts[0] == "agent":
+        if len(parts) < 2:
+            return False  # bare "agent" dir entry — not a file
+
+        subdir = parts[1]
+
+        # Flat files directly under agent/ — templates like progress.template.yaml
+        if len(parts) == 2:
+            name = parts[1]
+            # Only copy *.template.* files; skip live files like progress.yaml
+            return ".template." in name
+
+        # Skip excluded subdirs entirely
+        if subdir in _SKIP_AGENT_SUBDIRS:
+            return False
+
+        # Template-only subdirs: only *.template.* files
+        if subdir in _TEMPLATE_ONLY_SUBDIRS:
+            name = parts[-1]
+            return ".template." in name
+
+        # Other subdirs (commands, schemas, index): copy everything
+        return True
+
+    # Anything else at top level that isn't AGENT.md — skip
+    return False
+
+
+def _copy_templates(src_root: Path, target: Path) -> int:
+    """Copy filtered template files from src_root into target. Returns file count."""
+    file_count = 0
+    for src_file in sorted(src_root.rglob("*")):
+        if not src_file.is_file():
+            continue
+        try:
+            rel = src_file.relative_to(src_root)
+        except ValueError:
+            continue
+        if not _should_copy(rel):
+            continue
+        dest = target / rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(src_file, dest)
+        file_count += 1
+    return file_count
+
+
+def _generate_progress_yaml(project_name: str) -> str:
+    """Generate a minimal, valid progress.yaml for a fresh project."""
+    today = date.today().isoformat()
+    data = {
+        "project": {
+            "name": project_name,
+            "version": "0.1.0",
+            "started": today,
+            "status": "in_progress",
+            "current_milestone": None,
+            "description": f"ACP project: {project_name}",
+        },
+        "milestones": [],
+        "tasks": {},
+        "documentation": {
+            "design_documents": 0,
+            "milestone_documents": 0,
+            "pattern_documents": 0,
+            "task_documents": 0,
+            "last_updated": today,
+        },
+        "progress": {
+            "planning": 0,
+            "implementation": 0,
+            "testing": 0,
+            "documentation": 0,
+            "overall": 0,
+        },
+        "recent_work": [],
+        "next_steps": [
+            "Define requirements in agent/design/requirements.md",
+            "Create first milestone in agent/milestones/",
+            "Run `acp package list` to see installed packages",
+        ],
+        "notes": [],
+        "current_blockers": [],
+    }
+    return yaml.dump(data, default_flow_style=False, allow_unicode=True, sort_keys=False)
+
+
+def read_acp_version_from_agent_md(agent_md_path: Path) -> str | None:
+    """Extract **Version**: field from AGENT.md. Returns None if not found."""
+    if not agent_md_path.exists():
+        return None
+    text = agent_md_path.read_text(encoding="utf-8", errors="replace")
+    match = re.search(r"\*\*Version\*\*\s*:\s*(.+)", text)
+    return match.group(1).strip() if match else None
+
+
+@app.callback(invoke_without_command=True)
+def init(
+    path: Path = typer.Argument(Path("."), help="Directory to initialize. Use '.' for current."),
+    force: bool = typer.Option(False, "--force", help="Overwrite existing agent/ directory."),
+    branch: str = typer.Option("mainline", "--branch", help="agent-context-protocol branch to fetch."),
+) -> None:
+    """Bootstrap a new ACP project at PATH (default: current directory).
+
+    Fetches templates from agent-context-protocol (GitHub) at runtime.
+    Requires git on PATH.
+    """
+    target = path.resolve()
+    agent_dir = target / "agent"
+
+    # Guard: already initialized
+    if agent_dir.exists() and not force:
+        console.print(
+            Text(
+                f"[error] ACP project already initialized at {target}\n"
+                "        Use --force to overwrite.",
+                style="bold red",
+            )
+        )
+        raise typer.Exit(code=1)
+
+    # Create target directory if it doesn't exist
+    target.mkdir(parents=True, exist_ok=True)
+
+    console.print(f"[bold]Bootstrapping ACP project at[/bold] {target}")
+    console.print("  Fetching templates from agent-context-protocol…")
+
+    try:
+        with fetch_acp_templates(branch=branch) as src_root:
+            file_count = _copy_templates(src_root, target)
+    except RuntimeError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(code=1)
+
+    console.print(f"  [green]✓[/green] Copied {file_count} template files")
+
+    # Generate agent/progress.yaml (project-specific; not a template)
+    progress_path = agent_dir / "progress.yaml"
+    progress_path.parent.mkdir(parents=True, exist_ok=True)
+    progress_path.write_text(
+        _generate_progress_yaml(project_name=target.name),
+        encoding="utf-8",
+    )
+    console.print("  [green]✓[/green] Created agent/progress.yaml")
+
+    console.print()
+    console.print("[bold green]Done![/bold green] ACP project initialized.")
+    console.print()
+    console.print("[bold]Next steps:[/bold]")
+    if str(path) != ".":
+        console.print(f"  cd {path}")
+    console.print("  Define requirements in [cyan]agent/design/requirements.md[/cyan]")
+    console.print("  Run [cyan]acp package list[/cyan] to see installed packages")
+    console.print("  Start drafting milestones and tasks in [cyan]agent/milestones/[/cyan]")

acp/cli/main.py

@@ -0,0 +1,26 @@
+"""acp CLI entry point.
+
+Routes top-level subcommands (package, version, init) to their respective
+modules. Workflow commands (proceed, status, etc.) are intentionally NOT
+exposed here — those remain as markdown directives invoked via @acp.* syntax.
+"""
+from __future__ import annotations
+
+import typer
+
+from acp.cli import init as init_cmd
+from acp.cli import package as package_cmd
+from acp.cli import version as version_cmd
+
+app = typer.Typer(
+    help="ACP package manager and MCP integration.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+app.add_typer(package_cmd.app, name="package")
+app.add_typer(version_cmd.app, name="version")
+app.add_typer(init_cmd.app, name="init")
+
+
+if __name__ == "__main__":
+    app()

acp/cli/package.py

@@ -0,0 +1,183 @@
+"""acp package — package management subcommands."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from acp.core.package_manager import (
+    info_package,
+    install_package,
+    list_packages,
+    remove_package,
+    update_package,
+)
+
+console = Console()
+
+app = typer.Typer(
+    help="Package management: install, list, update, remove, info.",
+    no_args_is_help=True,
+)
+
+
+def _project_dir() -> Path:
+    return Path.cwd()
+
+
+@app.command()
+def install(
+    repo: str = typer.Argument(..., help="Git repository URL of the ACP package."),
+    global_install: bool = typer.Option(
+        False, "--global", help="Install to ~/.acp/agent/ instead of ./agent/."
+    ),
+    experimental: bool = typer.Option(
+        False, "--experimental", help="Include experimental package contents."
+    ),
+    force: bool = typer.Option(False, "--force", help="Reinstall even if already installed."),
+) -> None:
+    """Install an ACP package from a git repository."""
+    console.print(f"Installing [cyan]{repo}[/cyan]…")
+    try:
+        result = install_package(repo, _project_dir(), global_install, experimental, force)
+    except RuntimeError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(code=1)
+
+    pkg_name = result["name"]
+    pkg_version = result["version"]
+    installed = result["installed_files"]
+    warnings = result["warnings"]
+
+    console.print(
+        f"[green]Installed[/green] [bold]{pkg_name}[/bold] v{pkg_version}"
+    )
+
+    # Summary by kind
+    for kind, files in installed.items():
+        if files:
+            console.print(f"  {kind}: {len(files)} file(s)")
+
+    for w in warnings:
+        console.print(f"  [yellow]warn:[/yellow] {w}")
+
+
+@app.command(name="list")
+def list_packages_cmd(
+    global_install: bool = typer.Option(
+        False, "--global", help="List packages from ~/.acp/agent/manifest.yaml."
+    ),
+) -> None:
+    """List installed ACP packages."""
+    try:
+        packages = list_packages(_project_dir(), global_install)
+    except Exception as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(code=1)
+
+    if not packages:
+        scope = "global (~/.acp/agent/)" if global_install else "project (./agent/)"
+        console.print(f"No ACP packages installed in {scope}.")
+        return
+
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Name")
+    table.add_column("Version")
+    table.add_column("Files")
+    table.add_column("Updated")
+
+    for pkg in packages:
+        file_summary = ", ".join(
+            f"{count} {kind}" for kind, count in pkg["file_counts"].items()
+        )
+        updated = (pkg.get("updated_at") or "")[:10]  # date portion
+        table.add_row(pkg["name"], pkg["version"], file_summary, updated)
+
+    console.print(table)
+
+
+@app.command()
+def update(
+    name: str = typer.Argument(..., help="Package name to update."),
+    global_install: bool = typer.Option(
+        False, "--global", help="Update in global context."
+    ),
+) -> None:
+    """Update an installed ACP package to the latest version from its source."""
+    console.print(f"Updating [cyan]{name}[/cyan]…")
+    try:
+        result = update_package(name, _project_dir(), global_install)
+    except RuntimeError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(code=1)
+
+    console.print(
+        f"[green]Updated[/green] [bold]{result['name']}[/bold] to v{result['version']}"
+    )
+    for w in result.get("warnings", []):
+        console.print(f"  [yellow]warn:[/yellow] {w}")
+
+
+@app.command()
+def remove(
+    name: str = typer.Argument(..., help="Package name to remove."),
+    global_install: bool = typer.Option(
+        False, "--global", help="Remove from global context."
+    ),
+) -> None:
+    """Remove an installed ACP package."""
+    try:
+        result = remove_package(name, _project_dir(), global_install)
+    except RuntimeError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(code=1)
+
+    removed = result["removed"]
+    missing = result["missing"]
+    console.print(f"[green]Removed[/green] [bold]{name}[/bold] ({len(removed)} file(s) deleted)")
+    for m in missing:
+        console.print(f"  [yellow]warn:[/yellow] file not found: {m}")
+
+
+@app.command()
+def info(
+    name: str = typer.Argument(..., help="Package name to inspect."),
+    global_install: bool = typer.Option(
+        False, "--global", help="Look up in global context."
+    ),
+) -> None:
+    """Show details for an installed ACP package."""
+    try:
+        pkg = info_package(name, _project_dir(), global_install)
+    except Exception as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(code=1)
+
+    if pkg is None:
+        console.print(f"[red]Package '{name}' is not installed.[/red]")
+        raise typer.Exit(code=1)
+
+    console.print(f"[bold]{pkg['name']}[/bold] v{pkg['version']}")
+    console.print(f"  Source:       {pkg['source']}")
+    console.print(f"  Installed:    {(pkg.get('installed_at') or '')[:19]}")
+    console.print(f"  Updated:      {(pkg.get('updated_at') or '')[:19]}")
+    console.print("  Files:")
+    for kind, files in pkg.get("files", {}).items():
+        console.print(f"    {kind}: {len(files)}")
+        for f in files:
+            console.print(f"      - {f.get('name', '?')}")
+
+
+@app.command()
+def search(
+    query: str = typer.Argument(..., help="Search query (package name or keyword)."),
+) -> None:
+    """Search for ACP packages. (Registry not yet implemented.)"""
+    console.print(
+        "[yellow]acp package search[/yellow] requires a package registry that is not yet live.\n"
+        "To install a package directly, use:\n"
+        "  [cyan]acp package install <git-url>[/cyan]"
+    )
+    raise typer.Exit(code=0)

acp/cli/version.py

@@ -0,0 +1,190 @@
+"""acp version — manage a project's ACP methodology version.
+
+Commands:
+  show    — print the project's installed ACP version (from AGENT.md)
+  check   — compare project to agent-context-protocol mainline; report update status
+  update  — fetch latest templates and refresh project's agent/ artifacts
+
+Note: to upgrade the acp-mcp tool itself, run `uv tool upgrade acp-mcp` directly.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from acp.core.fetch import fetch_acp_templates
+
+console = Console()
+
+app = typer.Typer(
+    help="Manage the project's ACP methodology version.",
+    no_args_is_help=True,
+)
+
+_VERSION_RE = re.compile(r"\*\*Version\*\*\s*:\s*(.+)")
+
+
+def _find_project_root(start: Path) -> Path | None:
+    """Walk up from start looking for a directory containing agent/AGENT.md or agent/."""
+    current = start.resolve()
+    for candidate in [current, *current.parents]:
+        if (candidate / "AGENT.md").exists():
+            return candidate
+        if (candidate / "agent").is_dir():
+            return candidate
+    return None
+
+
+def _read_agent_md_version(agent_md: Path) -> str | None:
+    """Extract **Version**: from AGENT.md. Returns None if not found or file absent."""
+    if not agent_md.exists():
+        return None
+    text = agent_md.read_text(encoding="utf-8", errors="replace")
+    match = _VERSION_RE.search(text)
+    return match.group(1).strip() if match else None
+
+
+def _copy_templates_to_project(src_root: Path, project_root: Path) -> int:
+    """Copy ACP template files from a clone root into an existing project.
+
+    Uses the same filter logic as `acp init`: only template files are copied,
+    preserving user-authored project-specific content.
+
+    Returns the count of files written.
+    """
+    from acp.cli.init import _copy_templates
+    return _copy_templates(src_root, project_root)
+
+
+@app.command()
+def show(
+    project: Path = typer.Option(
+        Path("."),
+        "--project",
+        help="Project directory (default: current directory).",
+    ),
+) -> None:
+    """Print the project's installed ACP version (from AGENT.md)."""
+    root = _find_project_root(project)
+    if root is None:
+        console.print("[red]Not an ACP project:[/red] could not find project root.")
+        raise typer.Exit(code=1)
+
+    agent_md = root / "AGENT.md"
+    version = _read_agent_md_version(agent_md)
+
+    if version is None:
+        console.print(
+            f"[yellow]ACP version unknown.[/yellow] "
+            f"AGENT.md not found or missing **Version** field at {root}"
+        )
+        raise typer.Exit(code=1)
+
+    console.print(version)
+
+
+@app.command()
+def check(
+    project: Path = typer.Option(
+        Path("."),
+        "--project",
+        help="Project directory (default: current directory).",
+    ),
+    branch: str = typer.Option("mainline", "--branch", help="Upstream branch to compare against."),
+) -> None:
+    """Compare the project's ACP version against agent-context-protocol mainline."""
+    root = _find_project_root(project)
+    if root is None:
+        console.print("[red]Not an ACP project:[/red] could not find project root.")
+        raise typer.Exit(code=1)
+
+    agent_md = root / "AGENT.md"
+    local_version = _read_agent_md_version(agent_md)
+
+    if local_version is None:
+        console.print(
+            "[yellow]ACP version unknown.[/yellow] "
+            f"AGENT.md missing or no **Version** field at {root}."
+        )
+        raise typer.Exit(code=1)
+
+    console.print(f"Project ACP version: [bold]{local_version}[/bold]")
+    console.print(f"Fetching upstream version from agent-context-protocol ({branch})…")
+
+    try:
+        with fetch_acp_templates(branch=branch) as src_root:
+            upstream_version = _read_agent_md_version(src_root / "AGENT.md")
+    except RuntimeError as exc:
+        console.print(f"[red]Could not fetch upstream:[/red] {exc}")
+        raise typer.Exit(code=1)
+
+    if upstream_version is None:
+        console.print("[yellow]Upstream AGENT.md missing **Version** field.[/yellow]")
+        raise typer.Exit(code=1)
+
+    console.print(f"Upstream ACP version: [bold]{upstream_version}[/bold]")
+
+    if local_version == upstream_version:
+        console.print("[green]Up to date.[/green]")
+    else:
+        console.print(
+            f"[yellow]Update available:[/yellow] {local_version} → {upstream_version}"
+        )
+        console.print("  Run [cyan]acp version update[/cyan] to refresh.")
+
+
+@app.command()
+def update(
+    project: Path = typer.Option(
+        Path("."),
+        "--project",
+        help="Project directory (default: current directory).",
+    ),
+    branch: str = typer.Option("mainline", "--branch", help="Upstream branch to fetch from."),
+    force: bool = typer.Option(False, "--force", help="Apply updates even if versions match."),
+) -> None:
+    """Refresh the project's ACP artifacts from agent-context-protocol mainline.
+
+    Only template files are updated. Project-specific content (your design docs,
+    task instances, etc.) is not touched.
+
+    Requires git on PATH.
+    """
+    root = _find_project_root(project)
+    if root is None:
+        console.print("[red]Not an ACP project:[/red] could not find project root.")
+        raise typer.Exit(code=1)
+
+    # Read current local version for user-facing output (best-effort)
+    agent_md = root / "AGENT.md"
+    local_version = _read_agent_md_version(agent_md)
+    if local_version:
+        console.print(f"Current ACP version: [bold]{local_version}[/bold]")
+
+    console.print(f"Fetching latest templates from agent-context-protocol ({branch})…")
+
+    try:
+        with fetch_acp_templates(branch=branch) as src_root:
+            upstream_version = _read_agent_md_version(src_root / "AGENT.md")
+
+            if not force and local_version and upstream_version == local_version:
+                console.print(f"[green]Already up to date.[/green] ({local_version})")
+                return
+
+            file_count = _copy_templates_to_project(src_root, root)
+    except RuntimeError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(code=1)
+
+    console.print(f"  [green]✓[/green] Updated {file_count} template files")
+
+    if upstream_version:
+        console.print(f"  ACP version: [bold]{upstream_version}[/bold]")
+
+    console.print("[bold green]Done![/bold green] ACP templates refreshed.")
+    console.print(
+        "  Note: your project-specific docs (designs, tasks, milestones) are unchanged."
+    )

acp/core/__init__.py

@@ -0,0 +1 @@
+"""Core library — pure functions, no CLI/MCP surface."""