agentsmd 1.0.0__py3-none-any.whl

agentsmd/__init__.py

@@ -0,0 +1,2 @@
+"""AgentsMD - Intelligent workspace scaffolding and file synchronization."""
+__version__ = "1.0.0"

agentsmd/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for AgentsMD CLI."""
+import sys
+from agentsmd.cli import app
+
+if __name__ == "__main__":
+    sys.exit(app())

agentsmd/api_client.py

@@ -0,0 +1,187 @@
+"""Thin HTTP client for the AgentsMD backend API."""
+
+import base64
+import os
+from pathlib import Path
+from typing import Optional
+
+import httpx
+
+
+class APIClient:
+    """HTTP client that talks to the AgentsMD backend.
+
+    All sync intelligence lives on the server. This client just
+    sends files and receives results.
+    """
+
+    def __init__(self, token: str, base_url: Optional[str] = None):
+        self.base_url = base_url or os.environ.get(
+            "AGENTSMD_API_URL", "https://api.agentsmd.com"
+        )
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=60.0,
+        )
+
+    async def validate_token(self) -> dict:
+        """Validate the API token against the backend."""
+        resp = await self._client.post("/api/v1/auth/validate-token")
+        resp.raise_for_status()
+        return resp.json()
+
+    async def sync(self, workspace_id: str, machine_id: str, workspace_path: str) -> dict:
+        """Send all local files to the backend for sync.
+
+        The backend handles hashing, diffing, vector clocks, and R2 storage.
+        Returns sync results including files to download.
+        """
+        files = _collect_files(workspace_path)
+
+        upload_files = []
+        for name, content in files.items():
+            upload_files.append(("files", (name, content, "application/octet-stream")))
+
+        resp = await self._client.post(
+            "/api/v1/sync",
+            data={"workspace_id": workspace_id, "machine_id": machine_id},
+            files=upload_files,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    async def get_status(self, workspace_id: str) -> dict:
+        """Get workspace sync status from the backend."""
+        resp = await self._client.get(
+            "/api/v1/sync/status",
+            params={"workspace_id": workspace_id},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+
+def _load_gitignore_patterns(workspace: Path) -> set[str]:
+    """Load patterns from .gitignore if it exists."""
+    gitignore = workspace / ".gitignore"
+    if not gitignore.exists():
+        return set()
+
+    patterns = set()
+    for line in gitignore.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if line and not line.startswith("#"):
+            patterns.add(line)
+    return patterns
+
+
+def _is_ignored(relative_path: str, gitignore_patterns: set[str]) -> bool:
+    """Check if a relative path matches any .gitignore pattern."""
+    for pattern in gitignore_patterns:
+        if pattern.endswith("/"):
+            # Directory pattern — match if path starts with it
+            if relative_path.startswith(pattern) or relative_path.startswith(pattern.rstrip("/")):
+                return True
+        elif pattern.startswith("*"):
+            # Glob pattern like *.log
+            import fnmatch
+            if fnmatch.fnmatch(relative_path, pattern) or fnmatch.fnmatch(Path(relative_path).name, pattern):
+                return True
+        else:
+            # Exact match or prefix
+            if relative_path == pattern or relative_path.startswith(pattern + "/"):
+                return True
+    return False
+
+
+def _collect_files(workspace_path: str) -> dict[str, bytes]:
+    """Read AgentsMD workspace files into a dict.
+
+    Syncs only the files that agentsmd manages:
+    - AGENTS.md, CLAUDE.md (and other agent config files)
+    - memory/ directory
+    - prompts/ directory
+    - .agentsmd/ directory (including config.yml)
+
+    Additionally respects .gitignore patterns.
+    """
+    workspace = Path(workspace_path)
+    files = {}
+    gitignore = _load_gitignore_patterns(workspace)
+
+    # Root-level agent config files
+    agent_files = ["AGENTS.md", "CLAUDE.md", ".cursorrules", ".windsurfrules"]
+    for name in agent_files:
+        path = workspace / name
+        if path.exists() and not _is_ignored(name, gitignore):
+            files[name] = path.read_bytes()
+
+    # Tool directories
+    tool_dirs = [".cursor/rules", ".windsurf/rules", ".github/instructions"]
+    for dir_path in tool_dirs:
+        full_dir = workspace / dir_path
+        if full_dir.is_dir():
+            for file_path in full_dir.rglob("*"):
+                if file_path.is_file():
+                    try:
+                        relative = str(file_path.relative_to(workspace))
+                        if not _is_ignored(relative, gitignore):
+                            files[relative] = file_path.read_bytes()
+                    except (IOError, PermissionError):
+                        pass
+
+    # GitHub Copilot instructions file
+    copilot_file = workspace / ".github" / "copilot-instructions.md"
+    if copilot_file.exists():
+        relative = ".github/copilot-instructions.md"
+        if not _is_ignored(relative, gitignore):
+            files[relative] = copilot_file.read_bytes()
+
+    # .agentsmd/ directory
+    agentsmd_dir = workspace / ".agentsmd"
+    if agentsmd_dir.is_dir():
+        for file_path in agentsmd_dir.rglob("*"):
+            if file_path.is_file():
+                try:
+                    relative = str(file_path.relative_to(workspace))
+                    if not _is_ignored(relative, gitignore):
+                        files[relative] = file_path.read_bytes()
+                except (IOError, PermissionError):
+                    pass
+
+    # memory/ directory
+    memory_dir = workspace / "memory"
+    if memory_dir.exists():
+        for file_path in memory_dir.rglob("*"):
+            if file_path.is_file():
+                try:
+                    relative = str(file_path.relative_to(workspace))
+                    if not _is_ignored(relative, gitignore):
+                        files[relative] = file_path.read_bytes()
+                except (IOError, PermissionError):
+                    pass
+
+    # prompts/ directory
+    prompts_dir = workspace / "prompts"
+    if prompts_dir.exists():
+        for file_path in prompts_dir.rglob("*"):
+            if file_path.is_file():
+                try:
+                    relative = str(file_path.relative_to(workspace))
+                    if not _is_ignored(relative, gitignore):
+                        files[relative] = file_path.read_bytes()
+                except (IOError, PermissionError):
+                    pass
+
+    return files
+
+
+def write_downloaded_files(workspace_path: str, downloaded: list[dict]) -> int:
+    """Write downloaded files from sync result to disk."""
+    count = 0
+    for item in downloaded:
+        file_path = Path(workspace_path) / item["path"]
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_bytes(base64.b64decode(item["content"]))
+        count += 1
+    return count

agentsmd/auth/__init__.py

@@ -0,0 +1,12 @@
+"""Authentication module for AgentsMD.
+
+Handles API token management and credential storage.
+"""
+
+from agentsmd.auth.commands import run_login, run_logout, require_token
+
+__all__ = [
+    "run_login",
+    "run_logout",
+    "require_token",
+]

agentsmd/auth/commands.py

@@ -0,0 +1,40 @@
+"""Authentication command implementations."""
+
+import sys
+from typing import Optional
+from agentsmd.config import get_token, save_token, clear_credentials
+
+def require_token(cli_token: Optional[str] = None) -> str:
+    """Ensure a token is present, otherwise exit with instructions."""
+    token = get_token(cli_token)
+    if token:
+        return token
+
+    print("Error: Authentication required.")
+    print("Please generate an API token at https://app.agentsmd.com/settings/tokens")
+    print("and provide it via the --token flag, or the AGENTSMD_API_TOKEN environment variable.")
+    print("You can also save it globally using: agentsmd login --token <TOKEN>")
+    sys.exit(1)
+
+async def run_login(token: Optional[str] = None) -> None:
+    """Run authentication token saving flow."""
+    if not token:
+        print("Error: No token provided.")
+        print("Please generate an API token at https://app.agentsmd.com/settings/tokens")
+        print("and run: agentsmd login --token <TOKEN>")
+        sys.exit(1)
+
+    save_token(token)
+    print("Token saved successfully to ~/.agentsmd/credentials.json")
+    print("You are now authenticated!")
+
+async def run_logout() -> None:
+    """Clear local credentials and logout."""
+    token = get_token()
+    if not token:
+        print("Not logged in.")
+        return
+
+    clear_credentials()
+    print("Credentials cleared from ~/.agentsmd/")
+    print("You are now logged out.")

agentsmd/cli.py

@@ -0,0 +1,250 @@
+"""AgentsMD CLI - Command-line interface.
+
+Orchestrates workspace initialization, synchronization, and authentication.
+"""
+
+import sys
+import logging
+import typer
+from pathlib import Path
+from typing import Optional
+
+logging.basicConfig(level=logging.INFO, format="%(message)s")
+logger = logging.getLogger(__name__)
+
+app = typer.Typer(
+    name="agentsmd",
+    help="AgentsMD - Intelligent workspace scaffolding and file synchronization",
+    add_completion=False,
+    no_args_is_help=True
+)
+
+
+@app.command(name="init")
+def init_cmd():
+    """Initialize a new workspace."""
+    try:
+        from agentsmd.init.commands import run as run_init
+        import asyncio
+        asyncio.run(run_init())
+    except KeyboardInterrupt:
+        print("\n\nInitialization cancelled.")
+        sys.exit(0)
+    except Exception as e:
+        logger.error(f"Initialization failed: {e}")
+        raise typer.Exit(code=1)
+
+
+@app.command(name="sync")
+def sync_cmd(
+    workspace_path: Optional[Path] = typer.Argument(
+        None,
+        help="Path to workspace directory"
+    )
+):
+    """Synchronize workspace to/from Cloudflare R2."""
+    try:
+        from agentsmd.sync.commands import run as run_sync
+        import asyncio
+        asyncio.run(run_sync(workspace_path=str(workspace_path) if workspace_path else None))
+    except Exception as e:
+        logger.error(f"Sync failed: {e}")
+        raise typer.Exit(code=1)
+
+
+@app.command(name="status")
+def status_cmd(
+    workspace_path: Optional[Path] = typer.Argument(
+        None,
+        help="Path to workspace directory"
+    )
+):
+    """Show workspace synchronization status."""
+    try:
+        from agentsmd.sync.commands import run_status
+        import asyncio
+        asyncio.run(run_status(workspace_path=str(workspace_path) if workspace_path else None))
+    except Exception as e:
+        logger.error(f"Status check failed: {e}")
+        raise typer.Exit(code=1)
+
+
+@app.command(name="login")
+def login_cmd(
+    token: Optional[str] = typer.Option(
+        None,
+        "--token",
+        "-t",
+        help="API token to save globally"
+    )
+):
+    """Authenticate via API token."""
+    try:
+        from agentsmd.auth.commands import run_login
+        import asyncio
+        asyncio.run(run_login(token))
+    except Exception as e:
+        logger.error(f"Login failed: {e}")
+        raise typer.Exit(code=1)
+
+
+@app.command(name="logout")
+def logout_cmd():
+    """Clear local credentials."""
+    try:
+        from agentsmd.auth.commands import run_logout
+        import asyncio
+        asyncio.run(run_logout())
+    except Exception as e:
+        logger.error(f"Logout failed: {e}")
+        raise typer.Exit(code=1)
+
+
+@app.command(name="migrate")
+def migrate_cmd(
+    source: str = typer.Option(..., "--from", help="Source format (agents, claude, cursor, windsurf, copilot)"),
+    target: Optional[str] = typer.Option(None, "--to", help="Target format (default: agents + re-derive all)"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Print output without writing files"),
+):
+    """Convert between AI tool config formats."""
+    from agentsmd.converter.migrate import run_migrate
+    result = run_migrate(Path.cwd(), source_format=source, target_format=target, dry_run=dry_run)
+
+    if not result.success:
+        print(f"Error: {result.error}")
+        raise typer.Exit(code=1)
+
+    if dry_run and result.output:
+        print(result.output)
+    else:
+        for f in result.files_written:
+            print(f"  Written: {f}")
+        print(f"\nMigration complete. {len(result.files_written)} file(s) written.")
+
+
+@app.command(name="reconcile")
+def reconcile_cmd(
+    source: Optional[str] = typer.Option(None, "--from", help="Force source format (default: auto-detect)"),
+):
+    """Re-derive all tool config formats from the source of truth."""
+    from agentsmd.converter.reconcile import reconcile
+    result = reconcile(Path.cwd(), source_format=source)
+
+    if not result.success:
+        print(f"Error: {result.error}")
+        raise typer.Exit(code=1)
+
+    if result.changed_files:
+        print(f"Changed files: {result.changed_files}")
+    if result.files_written:
+        for f in result.files_written:
+            print(f"  Written: {f}")
+        print(f"\nReconcile complete. {len(result.files_written)} file(s) updated.")
+    else:
+        print("All formats are in sync. No changes needed.")
+
+
+@app.command(name="tool-list")
+def tool_list_cmd():
+    """Show detected AI tools in this workspace."""
+    from agentsmd.converter.detector import detect_tools
+    from agentsmd.converter.registry import FORMATS
+
+    workspace = Path.cwd()
+    detected = detect_tools(workspace)
+
+    if not detected:
+        print("No AI tool config files detected.")
+        print("Default: agents (AGENTS.md)")
+        return
+
+    print("Detected tools:")
+    for fmt in detected:
+        info = FORMATS.get(fmt, {})
+        files = info.get("files", [])
+        dirs = info.get("dirs", [])
+        locations = files + dirs
+        location_str = ", ".join(locations)
+
+        count = ""
+        for d in dirs:
+            full_dir = workspace / d
+            if full_dir.is_dir():
+                rule_files = list(full_dir.glob("*"))
+                if rule_files:
+                    count = f" — {len(rule_files)} rule(s)"
+
+        print(f"  ✓ {fmt:10s} ({location_str}{count})")
+
+    print(f"\nDefault: agents (AGENTS.md)")
+
+
+@app.command(name="tool-add")
+def tool_add_cmd():
+    """Register a custom AI tool interactively."""
+    print("Add Custom Tool")
+    print("=" * 40)
+    print()
+
+    name = input("Tool name: ").strip()
+    if not name:
+        print("Tool name is required.")
+        raise typer.Exit(code=1)
+
+    filename = input("Config filename: ").strip()
+    if not filename:
+        print("Filename is required.")
+        raise typer.Exit(code=1)
+
+    is_dir = input("Is directory-based? (y/n): ").strip().lower() == "y"
+
+    print()
+    print("Map markdown headings to canonical sections.")
+    print("Press Enter to skip a mapping.")
+    print()
+
+    section_mappings = {}
+    canonical_sections = ["overview", "rules", "constraints", "context", "workflow", "testing"]
+    for section in canonical_sections:
+        heading = input(f"  Which heading maps to '{section}'? ").strip()
+        if heading:
+            section_mappings[heading.lower()] = section
+
+    config_path = Path.cwd() / ".agentsmd" / "config.yml"
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    import yaml
+
+    config = {}
+    if config_path.exists():
+        try:
+            config = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+        except Exception:
+            config = {}
+
+    custom_tools = config.get("tools", [])
+    custom_tools.append({
+        "name": name,
+        "filename": filename,
+        "is_directory": is_dir,
+        "heading_mappings": section_mappings,
+    })
+    config["tools"] = custom_tools
+
+    config_path.write_text(yaml.dump(config, default_flow_style=False), encoding="utf-8")
+    print(f"\n✓ {name} registered in .agentsmd/config.yml")
+    print("✓ Run 'agentsmd sync' to reconcile.")
+
+
+@app.callback()
+def main(ctx: typer.Context) -> None:
+    """Main entry point."""
+    if ctx.resilient_parsing:
+        return
+
+    import agentsmd
+    typer.echo(f"AgentsMD v{agentsmd.__version__}")
+
+
+if __name__ == "__main__":
+    app()

agentsmd/config.py

@@ -0,0 +1,58 @@
+"""Configuration and credential management for AgentsMD."""
+
+import os
+import json
+from pathlib import Path
+from typing import Optional
+
+CONFIG_DIR = Path.home() / ".agentsmd"
+CREDENTIALS_FILE = CONFIG_DIR / "credentials.json"
+
+def _ensure_config_dir() -> None:
+    """Ensure ~/.agentsmd directory exists."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+def get_token(cli_token: Optional[str] = None) -> Optional[str]:
+    """Get stored credentials from local storage, env var, or CLI flag.
+
+    Order of precedence:
+    1. CLI Flag
+    2. AGENTSMD_API_TOKEN environment variable
+    3. credentials.json file
+    """
+    if cli_token:
+        return cli_token
+
+    if "AGENTSMD_API_TOKEN" in os.environ:
+        return os.environ["AGENTSMD_API_TOKEN"]
+
+    if not CREDENTIALS_FILE.exists():
+        return None
+
+    try:
+        with open(CREDENTIALS_FILE, "r") as f:
+            data = json.load(f)
+            return data.get("api_token")
+    except (json.JSONDecodeError, KeyError):
+        return None
+
+def save_token(token: str) -> None:
+    """Save token to local storage."""
+    _ensure_config_dir()
+
+    data = {
+        "api_token": token,
+    }
+
+    with open(CREDENTIALS_FILE, "w") as f:
+        json.dump(data, f, indent=2)
+
+def clear_credentials() -> None:
+    """Remove stored credentials."""
+    if CREDENTIALS_FILE.exists():
+        CREDENTIALS_FILE.unlink()
+
+
+def get_api_url() -> str:
+    """Get the backend API base URL."""
+    return os.environ.get("AGENTSMD_API_URL", "https://api.agentsmd.com")

agentsmd/converter/__init__.py

@@ -0,0 +1,12 @@
+from agentsmd.converter.canonical import AgentSection, CanonicalModel
+from agentsmd.converter.registry import get_parser, get_renderer, list_formats
+from agentsmd.converter.detector import detect_tools
+
+__all__ = [
+    "AgentSection",
+    "CanonicalModel",
+    "get_parser",
+    "get_renderer",
+    "list_formats",
+    "detect_tools",
+]

agentsmd/converter/canonical.py

@@ -0,0 +1,61 @@
+"""Canonical model for agent configuration sections."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from pydantic import BaseModel
+
+SECTION_FIELDS: List[str] = [
+    "overview",
+    "rules",
+    "constraints",
+    "context",
+    "workflow",
+    "testing",
+    "file_structure",
+    "documentation",
+    "environment",
+]
+
+
+class AgentSection(BaseModel):
+    """A single section within an agent configuration."""
+
+    heading: str
+    content: str
+    trigger: Optional[str] = None
+    globs: Optional[List[str]] = None
+    description: Optional[str] = None
+
+
+class CanonicalModel(BaseModel):
+    """Canonical representation of all agent configuration sections."""
+
+    overview: Optional[AgentSection] = None
+    rules: Optional[AgentSection] = None
+    constraints: Optional[AgentSection] = None
+    context: Optional[AgentSection] = None
+    workflow: Optional[AgentSection] = None
+    testing: Optional[AgentSection] = None
+    file_structure: Optional[AgentSection] = None
+    documentation: Optional[AgentSection] = None
+    environment: Optional[AgentSection] = None
+    extras: List[AgentSection] = []
+
+    def all_sections(self) -> List[AgentSection]:
+        """Return all non-None named sections plus extras."""
+        sections: List[AgentSection] = []
+        for field_name in SECTION_FIELDS:
+            section = getattr(self, field_name)
+            if section is not None:
+                sections.append(section)
+        sections.extend(self.extras)
+        return sections
+
+    def set_section(self, name: str, section: AgentSection) -> None:
+        """Set a named field if it matches a known field, otherwise append to extras."""
+        if name in SECTION_FIELDS:
+            setattr(self, name, section)
+        else:
+            self.extras.append(section)

agentsmd/converter/detector.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from agentsmd.converter.registry import FORMATS
+
+
+def detect_tools(workspace_path: Path) -> list[str]:
+    """Auto-detect active tools from workspace file/directory presence."""
+    detected: list[str] = []
+    for format_name, info in FORMATS.items():
+        found = False
+        for file_pattern in info.get("files", []):
+            if (workspace_path / file_pattern).exists():
+                found = True
+                break
+        if not found:
+            for dir_pattern in info.get("dirs", []):
+                if (workspace_path / dir_pattern).is_dir():
+                    found = True
+                    break
+        if found:
+            detected.append(format_name)
+    return detected