mact-cli 1.0.0__py3-none-any.whl

cli/__init__.py

@@ -0,0 +1 @@
+"""MACT Tunnel Client CLI package"""

cli/cli.py

@@ -0,0 +1,380 @@
+"""MACT CLI for Unit 3 - Tunnel Client
+
+Complete implementation with:
+- Developer initialization
+- Room creation with automatic tunnel and hook setup
+- Room joining with automatic tunnel and hook setup
+- Room leaving with tunnel cleanup
+- Status command to show active rooms
+
+Features:
+- Automatic frpc tunnel management
+- Git post-commit hook installation
+- Room membership tracking
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Dict, Optional
+import requests
+
+from .frpc_manager import FrpcManager, TunnelConfig
+from .hook import install_post_commit
+from .room_config import RoomConfig, RoomMembership
+
+def get_config_path() -> Path:
+    # Resolve HOME at runtime so tests can monkeypatch HOME before import
+    home = os.getenv("HOME") or str(Path.home())
+    return Path(home) / ".mact_config.json"
+
+
+DEFAULT_BACKEND = os.getenv("BACKEND_BASE_URL", "http://localhost:5000")
+DEFAULT_FRP_SERVER = os.getenv("FRP_SERVER_ADDR", "127.0.0.1")
+DEFAULT_FRP_PORT = int(os.getenv("FRP_SERVER_PORT", "7100"))
+
+
+def load_config() -> Dict[str, str]:
+    cfg_path = get_config_path()
+    if cfg_path.exists():
+        try:
+            with cfg_path.open("r") as fh:
+                return json.load(fh)
+        except Exception:
+            return {}
+    return {}
+
+
+def save_config(cfg: Dict[str, str]) -> None:
+    cfg_path = get_config_path()
+    with cfg_path.open("w") as fh:
+        json.dump(cfg, fh)
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    cfg = load_config()
+    cfg["developer_id"] = args.name
+    save_config(cfg)
+    print(f"Initialized developer_id={args.name} (saved to {get_config_path()})")
+    return 0
+
+
+def cmd_create(args: argparse.Namespace) -> int:
+    """Create a new room with automatic tunnel and hook setup."""
+    cfg = load_config()
+    developer_id = cfg.get("developer_id")
+    if not developer_id:
+        print("Error: Developer ID not set. Run 'mact init --name <your_name>' first.")
+        return 1
+    
+    # Support both syntax styles: positional and -project flag
+    project_name = args.project or getattr(args, 'project_flag', None)
+    if not project_name:
+        print("Error: Project name required. Use: mact create TelegramBot -port 5000")
+        return 1
+    
+    # Get local port (support both --local-port and -port)
+    local_port = getattr(args, 'port', None) or 3000
+    
+    # Auto-generate subdomain if not provided
+    subdomain = args.subdomain
+    if not subdomain:
+        # Auto-generate: dev-{developer}-{project}
+        subdomain = f"dev-{developer_id}-{project_name.lower()}"
+    
+    # Construct full subdomain URL for backend
+    # If subdomain is already a full URL, use it; otherwise construct it
+    if subdomain.startswith("http://") or subdomain.startswith("https://"):
+        subdomain_url = subdomain
+    else:
+        subdomain_url = f"http://{subdomain}.localhost:7101"
+    
+    # Create room via backend
+    payload = {"project_name": project_name, "developer_id": developer_id, "subdomain_url": subdomain_url}
+    resp = requests.post(f"{DEFAULT_BACKEND}/rooms/create", json=payload, timeout=5)
+    if resp.status_code != 201:
+        print(f"Failed to create room: {resp.status_code} {resp.text}")
+        return 1
+    
+    data = resp.json()
+    room_code = data['room_code']
+    print(f"✓ Room created: {room_code} -> {data['public_url']}")
+    
+    # Save room membership
+    room_config = RoomConfig()
+    membership = RoomMembership(
+        room_code=room_code,
+        developer_id=developer_id,
+        subdomain_url=subdomain_url,  # Use the full URL
+        local_port=local_port,
+        backend_url=DEFAULT_BACKEND
+    )
+    room_config.add_room(membership)
+    print(f"✓ Room membership saved")
+    
+    # Start frpc tunnel if not in test mode
+    if not getattr(args, 'no_tunnel', False):
+        try:
+            frpc = FrpcManager()
+            # Extract subdomain from URL or use the subdomain variable (already computed above)
+            # subdomain variable contains the correct value (either user-provided or auto-generated)
+            tunnel_subdomain = subdomain
+            if "//" in subdomain:
+                # Full URL provided: extract subdomain part
+                tunnel_subdomain = subdomain.split("//")[-1].split(".")[0]
+            
+            tunnel = TunnelConfig(
+                room_code=room_code,
+                developer_id=developer_id,
+                local_port=local_port,
+                remote_subdomain=tunnel_subdomain,
+                server_addr=DEFAULT_FRP_SERVER,
+                server_port=DEFAULT_FRP_PORT
+            )
+            if frpc.start_tunnel(tunnel):
+                print(f"✓ Tunnel started: {tunnel_subdomain} -> localhost:{local_port}")
+            else:
+                print(f"✗ Failed to start tunnel (continuing anyway)")
+                print(f"  Tip: Check if frpc binary exists and frps server is running on port {DEFAULT_FRP_PORT}")
+        except Exception as e:
+            print(f"✗ Tunnel setup failed: {e} (continuing anyway)")
+            print(f"  Tip: Run with DEBUG=1 for full traceback")
+    
+    # Install git hook if in a git repo
+    if not getattr(args, 'no_hook', False):
+        git_dir = Path.cwd()
+        if (git_dir / ".git").exists():
+            try:
+                install_post_commit(git_dir, developer_id, room_code, DEFAULT_BACKEND)
+                print(f"✓ Git post-commit hook installed")
+            except Exception as e:
+                print(f"✗ Hook installation failed: {e}")
+        else:
+            print(f"ℹ Not a git repository; skipping hook installation")
+    
+    print(f"\n✓ Room '{room_code}' is ready!")
+    print(f"  Public URL: {data['public_url']}")
+    print(f"  Local dev: http://localhost:{local_port}")
+    return 0
+
+
+def cmd_join(args: argparse.Namespace) -> int:
+    """Join an existing room with automatic tunnel and hook setup."""
+    cfg = load_config()
+    developer_id = cfg.get("developer_id") or args.developer
+    
+    if not developer_id:
+        print("Error: Developer ID not set. Run 'mact init --name <your_name>' first or use --developer flag.")
+        return 1
+    
+    # Support both syntax styles: positional and -join flag
+    room_code = args.room or getattr(args, 'room_flag', None)
+    if not room_code:
+        print("Error: Room code required. Use: mact join XXXX-XXXX-XXXX -port 5023")
+        return 1
+    
+    # Get local port (support both styles)
+    local_port = getattr(args, 'port', None) or 3000
+    
+    # Auto-generate subdomain if not provided
+    subdomain = args.subdomain
+    if not subdomain:
+        # Auto-generate: dev-{developer}-{room}
+        subdomain = f"dev-{developer_id}-{room_code}"
+    
+    # Construct full subdomain URL for backend
+    if subdomain.startswith("http://") or subdomain.startswith("https://"):
+        subdomain_url = subdomain
+    else:
+        subdomain_url = f"http://{subdomain}.localhost:7101"
+    
+    # Join room via backend
+    payload = {"room_code": room_code, "developer_id": developer_id, "subdomain_url": subdomain_url}
+    resp = requests.post(f"{DEFAULT_BACKEND}/rooms/join", json=payload, timeout=5)
+    if resp.status_code != 200:
+        print(f"Failed to join room: {resp.status_code} {resp.text}")
+        return 1
+    
+    print(f"✓ Joined room: {room_code}")
+    
+    # Save room membership
+    room_config = RoomConfig()
+    membership = RoomMembership(
+        room_code=room_code,
+        developer_id=developer_id,
+        subdomain_url=subdomain_url,
+        local_port=local_port,
+        backend_url=DEFAULT_BACKEND
+    )
+    room_config.add_room(membership)
+    print(f"✓ Room membership saved")
+    
+    # Start frpc tunnel
+    if not getattr(args, 'no_tunnel', False):
+        try:
+            frpc = FrpcManager()
+            # Extract subdomain from URL or use as-is (subdomain variable already computed above)
+            tunnel_subdomain = subdomain
+            if "//" in subdomain:
+                # Full URL provided: extract subdomain part
+                tunnel_subdomain = subdomain.split("//")[-1].split(".")[0]
+            
+            tunnel = TunnelConfig(
+                room_code=room_code,
+                developer_id=developer_id,
+                local_port=local_port,
+                remote_subdomain=tunnel_subdomain,
+                server_addr=DEFAULT_FRP_SERVER,
+                server_port=DEFAULT_FRP_PORT
+            )
+            if frpc.start_tunnel(tunnel):
+                print(f"✓ Tunnel started: {tunnel_subdomain} -> localhost:{local_port}")
+            else:
+                print(f"✗ Failed to start tunnel (continuing anyway)")
+                print(f"  Tip: Check if frpc binary exists and frps server is running on port {DEFAULT_FRP_PORT}")
+        except Exception as e:
+            print(f"✗ Tunnel setup failed: {e} (continuing anyway)")
+            print(f"  Tip: Run with DEBUG=1 for full traceback")
+    
+    # Install git hook
+    if not getattr(args, 'no_hook', False):
+        git_dir = Path.cwd()
+        if (git_dir / ".git").exists():
+            try:
+                install_post_commit(git_dir, developer_id, room_code, DEFAULT_BACKEND)
+                print(f"✓ Git post-commit hook installed")
+            except Exception as e:
+                print(f"✗ Hook installation failed: {e}")
+        else:
+            print(f"ℹ Not a git repository; skipping hook installation")
+    
+    print(f"\n✓ Successfully joined room '{room_code}'!")
+    return 0
+
+
+def cmd_leave(args: argparse.Namespace) -> int:
+    """Leave a room and stop tunnel."""
+    cfg = load_config()
+    developer_id = cfg.get("developer_id") or args.developer
+    
+    if not developer_id:
+        print("Error: Developer ID not set. Run 'mact init --name <your_name>' first or use --developer flag.")
+        return 1
+    
+    # Leave room via backend
+    payload = {"room_code": args.room, "developer_id": developer_id}
+    resp = requests.post(f"{DEFAULT_BACKEND}/rooms/leave", json=payload, timeout=5)
+    if resp.status_code != 200:
+        print(f"Failed to leave room: {resp.status_code} {resp.text}")
+        return 1
+    
+    print(f"✓ Left room: {args.room}")
+    
+    # Stop tunnel
+    try:
+        frpc = FrpcManager()
+        if frpc.stop_tunnel(args.room, developer_id):
+            print(f"✓ Tunnel stopped")
+    except Exception as e:
+        print(f"✗ Failed to stop tunnel: {e}")
+    
+    # Remove room membership
+    room_config = RoomConfig()
+    if room_config.remove_room(args.room):
+        print(f"✓ Room membership removed")
+    
+    return 0
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    """Show active room memberships."""
+    room_config = RoomConfig()
+    rooms = room_config.list_rooms()
+    
+    if not rooms:
+        print("No active room memberships.")
+        print("Create a room with: mact create --project <name> --subdomain <url>")
+        return 0
+    
+    print(f"Active room memberships ({len(rooms)}):\n")
+    for room in rooms:
+        print(f"  Room: {room.room_code}")
+        print(f"    Developer: {room.developer_id}")
+        print(f"    Subdomain: {room.subdomain_url}")
+        if room.local_port:
+            print(f"    Local port: {room.local_port}")
+        
+        # Check tunnel status
+        try:
+            frpc = FrpcManager()
+            if frpc.is_running(room.room_code, room.developer_id):
+                print(f"    Tunnel: ✓ Running")
+            else:
+                print(f"    Tunnel: ✗ Not running")
+        except:
+            print(f"    Tunnel: ? Unknown")
+        print()
+    
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mact",
+        description="MACT - Mirrored Active Collaborative Tunnel CLI"
+    )
+    sub = parser.add_subparsers(dest="cmd", help="Command to run")
+
+    # init command
+    p_init = sub.add_parser("init", help="Initialize MACT with your developer ID")
+    p_init.add_argument("--name", required=True, help="Your developer ID/name")
+    p_init.set_defaults(func=cmd_init)
+
+    # create command
+    p_create = sub.add_parser("create", help="Create a new room")
+    p_create.add_argument("project", nargs="?", help="Project name for the room (positional)")
+    p_create.add_argument("-project", dest="project_flag", help="Project name (alternative)")
+    p_create.add_argument("-port", type=int, default=3000, help="Local port (default: 3000)")
+    p_create.add_argument("--subdomain", help="Your subdomain (auto-generated if not provided)")
+    p_create.add_argument("--no-tunnel", action="store_true", help="Skip tunnel setup")
+    p_create.add_argument("--no-hook", action="store_true", help="Skip git hook installation")
+    p_create.set_defaults(func=cmd_create)
+
+    # join command
+    p_join = sub.add_parser("join", help="Join an existing room")
+    p_join.add_argument("room", nargs="?", help="Room code to join (positional)")
+    p_join.add_argument("-join", dest="room_flag", help="Room code (alternative)")
+    p_join.add_argument("-port", type=int, default=3000, help="Local port (default: 3000)")
+    p_join.add_argument("--developer", help="Developer ID (uses init value if not specified)")
+    p_join.add_argument("--subdomain", help="Your subdomain (auto-generated if not provided)")
+    p_join.add_argument("--no-tunnel", action="store_true", help="Skip tunnel setup")
+    p_join.add_argument("--no-hook", action="store_true", help="Skip git hook installation")
+    p_join.set_defaults(func=cmd_join)
+
+    # leave command
+    p_leave = sub.add_parser("leave", help="Leave a room")
+    p_leave.add_argument("--room", required=True, help="Room code to leave")
+    p_leave.add_argument("--developer", help="Developer ID (uses init value if not specified)")
+    p_leave.set_defaults(func=cmd_leave)
+    
+    # status command
+    p_status = sub.add_parser("status", help="Show active room memberships")
+    p_status.set_defaults(func=cmd_status)
+
+    return parser
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return 1
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cli/frpc_manager.py

@@ -0,0 +1,132 @@
+"""FRPC tunnel management for MACT CLI.
+
+This module handles starting, stopping, and managing frpc tunnel client processes
+for developer rooms.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class TunnelConfig:
+    """Configuration for a single frpc tunnel."""
+    
+    room_code: str
+    developer_id: str
+    local_port: int
+    remote_subdomain: str
+    server_addr: str = "127.0.0.1"
+    server_port: int = 7100
+
+
+class FrpcManager:
+    """Manages frpc tunnel client processes."""
+    
+    def __init__(self, frpc_binary: Optional[str] = None):
+        self.frpc_binary = frpc_binary or self._find_frpc_binary()
+        self._processes: dict[str, subprocess.Popen] = {}
+        self._config_files: dict[str, Path] = {}
+    
+    def _find_frpc_binary(self) -> str:
+        """Find frpc binary in vendored location or PATH."""
+        # Try vendored binary first
+        vendored = Path(__file__).parent.parent / "third_party" / "frp" / "frpc"
+        if vendored.exists() and vendored.is_file():
+            return str(vendored.absolute())
+        
+        # Try PATH
+        frpc_path = shutil.which("frpc")
+        if frpc_path:
+            return frpc_path
+        
+        raise RuntimeError("frpc binary not found. Please install frp or set FRPC_BIN environment variable.")
+    
+    def _generate_config(self, tunnel: TunnelConfig) -> str:
+        """Generate frpc TOML configuration."""
+        return f"""# MACT frpc config for room {tunnel.room_code}
+serverAddr = "{tunnel.server_addr}"
+serverPort = {tunnel.server_port}
+
+[[proxies]]
+name = "{tunnel.room_code}-{tunnel.developer_id}"
+type = "http"
+localIP = "127.0.0.1"
+localPort = {tunnel.local_port}
+subdomain = "{tunnel.remote_subdomain}"
+"""
+    
+    def start_tunnel(self, tunnel: TunnelConfig) -> bool:
+        """Start an frpc tunnel for the given configuration."""
+        key = f"{tunnel.room_code}:{tunnel.developer_id}"
+        
+        # Check if already running
+        if key in self._processes:
+            proc = self._processes[key]
+            if proc.poll() is None:
+                return True  # Already running
+        
+        # Create temporary config file
+        config_content = self._generate_config(tunnel)
+        config_file = Path(tempfile.mkdtemp()) / f"frpc_{tunnel.room_code}.toml"
+        config_file.write_text(config_content)
+        self._config_files[key] = config_file
+        
+        # Start frpc
+        try:
+            proc = subprocess.Popen(
+                [self.frpc_binary, "-c", str(config_file)],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+            self._processes[key] = proc
+            return True
+        except Exception as e:
+            print(f"Failed to start frpc: {e}")
+            return False
+    
+    def stop_tunnel(self, room_code: str, developer_id: str) -> bool:
+        """Stop the frpc tunnel for the given room and developer."""
+        key = f"{room_code}:{developer_id}"
+        
+        if key not in self._processes:
+            return True  # Not running
+        
+        proc = self._processes[key]
+        if proc.poll() is None:
+            proc.terminate()
+            try:
+                proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+        
+        # Clean up
+        del self._processes[key]
+        if key in self._config_files:
+            try:
+                self._config_files[key].parent.rmdir()
+            except:
+                pass
+            del self._config_files[key]
+        
+        return True
+    
+    def is_running(self, room_code: str, developer_id: str) -> bool:
+        """Check if a tunnel is currently running."""
+        key = f"{room_code}:{developer_id}"
+        if key not in self._processes:
+            return False
+        proc = self._processes[key]
+        return proc.poll() is None
+    
+    def stop_all(self) -> None:
+        """Stop all running tunnels."""
+        for key in list(self._processes.keys()):
+            room, dev = key.split(":")
+            self.stop_tunnel(room, dev)

cli/hook.py

@@ -0,0 +1,45 @@
+"""Utilities for installing a Git post-commit hook that calls the backend /report-commit endpoint.
+
+This is a minimal helper used by the CLI to install a script into .git/hooks/post-commit
+that will POST to the coordination backend with commit info. The actual hook content
+is intentionally small and can be improved later.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+HOOK_TEMPLATE = """#!/usr/bin/env bash
+# MACT post-commit hook - this script posts commit details to the coordination backend
+# Usage: This file is written into .git/hooks/post-commit
+BACKEND_URL="__BACKEND_URL__"
+DEVELOPER_ID="__DEVELOPER_ID__"
+ROOM_CODE="__ROOM_CODE__"
+
+COMMIT_HASH=$(git rev-parse --short HEAD || true)
+BRANCH=$(git rev-parse --abbrev-ref HEAD || true)
+MSG=$(git log -1 --pretty=%B | tr -d '"' | tr -d "'" | head -c 200)
+
+if [ -z "$ROOM_CODE" ]; then
+  echo "MACT: ROOM_CODE not set; skipping report-commit"
+  exit 0
+fi
+
+curl -s -X POST "$BACKEND_URL/report-commit" \\
+  -H "Content-Type: application/json" \\
+  -d "{\\"room_code\\": \\"$ROOM_CODE\\", \\"developer_id\\": \\"$DEVELOPER_ID\\", \\"commit_hash\\": \\"$COMMIT_HASH\\", \\"branch\\": \\"$BRANCH\\", \\"commit_message\\": \\"$MSG\\"}" >/dev/null
+
+echo "✓ Commit reported to MACT (Room: $ROOM_CODE)"
+"""
+
+
+def install_post_commit(git_dir: Path, developer_id: str, room_code: str, backend_url: str = "http://localhost:5000") -> None:
+    hooks_dir = git_dir / ".git" / "hooks"
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    hook_path = hooks_dir / "post-commit"
+    content = HOOK_TEMPLATE.replace("__BACKEND_URL__", backend_url)
+    content = content.replace("__DEVELOPER_ID__", developer_id)
+    content = content.replace("__ROOM_CODE__", room_code)
+    with hook_path.open("w") as fh:
+        fh.write(content)
+    hook_path.chmod(0o755)

cli/room_config.py

@@ -0,0 +1,90 @@
+"""Room configuration management for MACT CLI.
+
+Tracks active room memberships and tunnel configurations.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+@dataclass
+class RoomMembership:
+    """Represents a developer's membership in a room."""
+    
+    room_code: str
+    developer_id: str
+    subdomain_url: str
+    local_port: Optional[int] = None
+    backend_url: str = "http://localhost:5000"
+    
+    def to_dict(self) -> dict:
+        return asdict(self)
+    
+    @classmethod
+    def from_dict(cls, data: dict) -> "RoomMembership":
+        return cls(**data)
+
+
+class RoomConfig:
+    """Manages room membership configuration."""
+    
+    def __init__(self, config_path: Optional[Path] = None):
+        if config_path is None:
+            home = Path.home()
+            config_path = home / ".mact_rooms.json"
+        self.config_path = config_path
+        self._rooms: Dict[str, RoomMembership] = {}
+        self.load()
+    
+    def load(self) -> None:
+        """Load room configurations from disk."""
+        if not self.config_path.exists():
+            self._rooms = {}
+            return
+        
+        try:
+            with self.config_path.open("r") as fh:
+                data = json.load(fh)
+                self._rooms = {
+                    room_code: RoomMembership.from_dict(room_data)
+                    for room_code, room_data in data.items()
+                }
+        except Exception:
+            self._rooms = {}
+    
+    def save(self) -> None:
+        """Save room configurations to disk."""
+        data = {
+            room_code: room.to_dict()
+            for room_code, room in self._rooms.items()
+        }
+        with self.config_path.open("w") as fh:
+            json.dump(data, fh, indent=2)
+    
+    def add_room(self, room: RoomMembership) -> None:
+        """Add or update a room membership."""
+        self._rooms[room.room_code] = room
+        self.save()
+    
+    def remove_room(self, room_code: str) -> bool:
+        """Remove a room membership."""
+        if room_code in self._rooms:
+            del self._rooms[room_code]
+            self.save()
+            return True
+        return False
+    
+    def get_room(self, room_code: str) -> Optional[RoomMembership]:
+        """Get room membership by room code."""
+        return self._rooms.get(room_code)
+    
+    def list_rooms(self) -> List[RoomMembership]:
+        """List all room memberships."""
+        return list(self._rooms.values())
+    
+    def has_room(self, room_code: str) -> bool:
+        """Check if developer is a member of a room."""
+        return room_code in self._rooms

mact_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,324 @@
+Metadata-Version: 2.4
+Name: mact-cli
+Version: 1.0.0
+Summary: MACT (Mirrored Active Collaborative Tunnel) - CLI tool for collaborative development
+Home-page: https://m-act.live
+Author: MACT Team
+Author-email: 22btcs042hy@manuu.edu.in
+License: MIT
+Project-URL: Homepage, https://m-act.live
+Project-URL: Documentation, https://github.com/mact/mact
+Project-URL: Repository, https://github.com/mact/mact
+Project-URL: Issues, https://github.com/mact/mact/issues
+Keywords: tunnel,development,collaboration,git,frp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Dynamic: author-email
+Dynamic: home-page
+Dynamic: requires-python
+
+# MACT (Mirrored Active Collaborative Tunnel)
+
+A collaborative development platform that provides a single, persistent public URL for project "rooms" that live-mirrors the localhost of the developer with the latest Git commit.
+
+## 🚀 Quick Start
+
+### For End Users (Install CLI)
+
+```bash
+# Install via pip (easy!)
+pip install git+https://github.com/int33k/M-ACT.git
+
+# Initialize
+mact init --name your-name
+
+# Create your first room (from your project directory)
+cd ~/your-project
+mact create TelegramBot -port 3000
+
+# 🎉 Your room is live!
+# Mirror:    https://telegrambot.m-act.live/
+# Dashboard: https://telegrambot.m-act.live/dashboard
+```
+
+See [.docs/QUICK_START.md](.docs/QUICK_START.md) for complete guide.
+
+### For Administrators (Run Server Locally)
+
+```bash
+# 1. Clone and setup
+git clone https://github.com/int33k/M-ACT.git
+cd M-ACT
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+# 2. Start services (3 terminals)
+python -m backend.app                    # Terminal 1: Backend (port 5000)
+./scripts/run_frp_local.sh              # Terminal 2: FRP server (port 7100)
+FRP_AUTOSTART=0 python -m proxy.app     # Terminal 3: Proxy (port 9000)
+```
+
+See [INSTALL.md](INSTALL.md) for detailed local development setup.  
+See [.docs/PRODUCTION_DEPLOYMENT_GUIDE.md](.docs/PRODUCTION_DEPLOYMENT_GUIDE.md) for production deployment.
+
+### For Server Administrators (Manage Production)
+
+Once deployed to DigitalOcean, use the admin CLI to manage rooms and users:
+
+```bash
+# SSH into your droplet
+ssh root@m-act.live
+
+# List all rooms
+mact-admin rooms list
+
+# Delete a specific room
+mact-admin rooms delete old-project
+
+# Clean up empty rooms
+mact-admin rooms cleanup
+
+# Check system health
+mact-admin system health
+
+# View logs
+mact-admin system logs backend
+```
+
+See [.docs/ADMIN_CLI_GUIDE.md](.docs/ADMIN_CLI_GUIDE.md) for complete admin reference.
+
+## What is MACT?
+
+MACT eliminates deployment delays in collaborative development:
+
+- 🏠 **Room-based collaboration** - Multiple developers share one permanent URL
+- 🔄 **Git-driven switching** - Latest commit author becomes "active developer"
+- 🪞 **Live mirroring** - Room URL auto-proxies to active developer's localhost
+- 🌐 **Subdomain routing** - Clean URLs: `project-name.m-act.live`
+- ⚡ **Zero configuration** - One CLI command sets up tunnel + git hooks
+- 📊 **Real-time dashboard** - WebSocket-powered status updates
+
+## Architecture
+
+```
+┌─────────────┐
+│   Browser   │ ← User accesses project-name.m-act.live
+└──────┬──────┘
+       │
+┌──────▼────────────────────────────────────────────┐
+│  Proxy (Port 9000)                                │
+│  • Subdomain routing                              │
+│  • WebSocket auto-refresh                         │
+│  • Dashboard UI                                   │
+└──────┬───────────────┬────────────────────────────┘
+       │               │
+┌──────▼──────┐   ┌────▼───────────────────┐
+│  Backend    │   │  FRP Server (Port 7100)│
+│  Port 5000  │   │  • Tunnel multiplexing │
+│  • Rooms    │   │  • Vhost HTTP (7101)   │
+│  • Commits  │   └────┬───────────────────┘
+└─────────────┘        │
+                  ┌────▼─────┐  ┌──────────┐
+                  │ Dev A    │  │ Dev B    │
+                  │ :3000    │  │ :3001    │
+                  │ (Active) │  │ (Idle)   │
+                  └──────────┘  └──────────┘
+```
+
+**Four Components:**
+1. **Backend** - Flask REST API managing rooms, participants, commits
+2. **Proxy** - Starlette/ASGI server with subdomain routing + WebSocket support
+3. **CLI** - Developer tool for room creation, joining, and tunnel management  
+4. **FRP** - Fast Reverse Proxy for localhost tunneling
+
+## Features
+
+### ✅ Core Functionality
+- **Subdomain-based routing** - `project-name.localhost:9000` → active developer
+- **Git-driven active developer** - Latest commit author gets the spotlight
+- **WebSocket auto-refresh** - Dashboard & mirror update instantly on commits
+- **Automatic tunnel setup** - One CLI command handles everything
+- **Real-time dashboard** - See participants, commits, active developer
+- **Production security** - Input validation, auth, XSS prevention
+
+### 🧪 Test Coverage  
+**36 tests passing** across all components:
+- Backend: 13 tests
+- Proxy: 8 tests  
+- CLI: 7 tests
+- FRP Manager: 5 tests
+- Integration: 3 tests
+
+### 📦 Technology Stack
+- **Backend**: Python 3.12 + Flask
+- **Proxy**: Starlette/ASGI + uvicorn  
+- **Tunneling**: frp v0.65.0 (vendored)
+- **Testing**: pytest
+- **Security**: Flask-Limiter + input validation
+
+## CLI Usage
+
+```bash
+# 1. Initialize your developer identity
+mact init --name your-name
+
+# 2. Create a room (from your git project directory)
+# Simple syntax: mact create PROJECT_NAME -port PORT
+mact create TelegramBot -port 5000
+
+# Your room is now accessible at:
+# 🪞 Mirror:    https://telegrambot.m-act.live/
+# 📊 Dashboard: https://telegrambot.m-act.live/dashboard
+
+# 3. Another developer joins
+mact join telegrambot -port 5001
+
+# 4. Make commits - active developer switches automatically!
+git commit -m "My feature"  # You become active
+# Mirror now shows YOUR localhost:5000
+
+# 5. Check status
+mact status
+
+# 6. Leave room
+mact leave --room telegrambot
+```
+
+**Key Features:**
+- ✨ **Simple syntax:** `mact create ProjectName -port 3000`
+- 🚀 **Auto-subdomain:** Generates subdomain automatically
+- 🔧 **Zero config:** One command does everything
+- 📦 **pip install:** No manual setup needed
+
+See [`.docs/QUICK_START.md`](.docs/QUICK_START.md) for complete guide.  
+See [`cli/README.md`](cli/README.md) for detailed CLI documentation.
+
+## API Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /rooms/create` | Create a new room |
+| `POST /rooms/join` | Join an existing room |
+| `POST /report-commit` | Report a Git commit (auto-called by git hook) |
+| `GET /get-active-url` | Get active developer's tunnel URL |
+| `GET /rooms/status` | Get room participants and state |
+| `GET /rooms/<room>/commits` | Get commit history |
+| `GET /health` | Health check |
+
+**Proxy Endpoints:**
+| Endpoint | Description |
+|----------|-------------|
+| `http://<room>.localhost:9000/` | Mirror - proxies to active developer |
+| `http://<room>.localhost:9000/dashboard` | Dashboard - room status UI |
+| `ws://<room>.localhost:9000/notifications` | WebSocket - real-time updates |
+
+See [`backend/README.md`](backend/README.md) for API examples.
+
+## Port Configuration
+
+| Service | Port | Purpose |
+|---------|------|---------|
+| Backend | 5000 | REST API |
+| Proxy | 9000 | Public entry point |
+| FRP Server | 7100 | Tunnel control |
+| FRP VHost | 7101 | HTTP tunnels (subdomain multiplexing) |
+| Developer localhost | 3000+ | Your local dev servers |
+
+## Testing
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run specific component
+pytest tests/test_backend.py -v
+pytest tests/test_proxy.py -v
+pytest tests/test_cli.py -v
+
+# Run with coverage
+pytest --cov=. tests/
+```
+
+**Test Status**: 36 tests passing (13 backend + 8 proxy + 7 CLI + 5 FRP + 3 integration)
+
+## Production Deployment
+
+MACT is production-ready with:
+- ✅ **Systemd services** with auto-restart
+- ✅ **Nginx configuration** for SSL/TLS termination
+- ✅ **Security hardening** (input validation, auth, XSS prevention)
+- ✅ **Deployment scripts** (setup, deploy, rollback)
+- ✅ **Wildcard DNS support** for subdomain routing
+
+### Quick Deploy (Ubuntu 22.04)
+
+```bash
+# 1. Setup server (as root)
+cd deployment/scripts
+./setup.sh
+
+# 2. Configure environment
+cp deployment/mact-*.env.template /etc/mact/
+# Edit env files with your settings
+
+# 3. Deploy
+./deploy.sh
+
+# 4. Configure DNS
+# Add wildcard DNS: *.m-act.live → YOUR_SERVER_IP
+
+# 5. Setup SSL (Let's Encrypt)
+certbot --nginx -d m-act.live -d "*.m-act.live"
+```
+
+See [`.docs/DEPLOYMENT.md`](.docs/DEPLOYMENT.md) for complete guide.
+
+### Security Features
+- Input validation on all endpoints
+- Bearer token authentication for admin endpoints
+- XSS prevention with HTML sanitization
+- Rate limiting (nginx + Flask-Limiter)
+- Security headers (X-Frame-Options, CSP, etc.)
+
+See [`.docs/SECURITY_THREAT_MODEL.md`](.docs/SECURITY_THREAT_MODEL.md) for threat analysis.
+
+## Documentation
+
+### 📚 User Guides
+- **[INSTALL.md](INSTALL.md)** - Installation and setup guide
+- **[cli/README.md](cli/README.md)** - CLI commands and usage
+- **[backend/README.md](backend/README.md)** - API reference
+- **[proxy/README.md](proxy/README.md)** - Proxy configuration
+
+### 🔧 Technical Documentation
+- **[.docs/PROJECT_CONTEXT.md](.docs/PROJECT_CONTEXT.md)** - Architecture and design decisions
+- **[.docs/DEPLOYMENT.md](.docs/DEPLOYMENT.md)** - Production deployment guide
+- **[.docs/SECURITY_THREAT_MODEL.md](.docs/SECURITY_THREAT_MODEL.md)** - Security analysis
+- **[.docs/WEBSOCKET_DESIGN.md](.docs/WEBSOCKET_DESIGN.md)** - WebSocket implementation
+- **[.docs/E2E_TEST_REPORT.md](.docs/E2E_TEST_REPORT.md)** - End-to-end testing results
+- **[ARCHITECTURE_NOTES.md](ARCHITECTURE_NOTES.md)** - URL standardization & nginx setup
+
+### 📖 Additional Resources
+- **[FRP_AUTOMATION.md](FRP_AUTOMATION.md)** - FRP tunnel automation guide
+- **[CLI_QUICKREF.md](CLI_QUICKREF.md)** - Quick CLI reference
+- **[.docs/PROGRESS_LOG.md](.docs/PROGRESS_LOG.md)** - Development history
+
+## Contributing
+
+Academic research project. Code follows "Build in Units" methodology with strict adherence to `PROJECT_CONTEXT.md`.
+
+## License
+
+MIT License - See LICENSE file for details.

mact_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+cli/__init__.py,sha256=FMFwvK7OHiX5551Bgc6ZwIrmoeraTcXt2AFYg6dnfg0,37
+cli/cli.py,sha256=CtBcRIxgJOhLRB6LY5QkQc1o1ejejs9h9554VZgHROQ,14314
+cli/frpc_manager.py,sha256=Yy5G_EawoXzr8Do138OfTWc1JUw4dz-ZpV7AIXi5gzk,4232
+cli/hook.py,sha256=4SJVBgfyoOvcYgCGSUImSHXMASNDrsoL78aeIbZTzzM,1828
+cli/room_config.py,sha256=N1cFxH0GLlV9YxCkckqAuyfTKsVtXiVWL61bAS4tXNc,2705
+mact_cli-1.0.0.dist-info/METADATA,sha256=IAY24rT0CExAnF7frK0xStbo6v8fPx-UnT9KIwnHLKI,11233
+mact_cli-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mact_cli-1.0.0.dist-info/entry_points.txt,sha256=5ca2QAJyrq0JI35JzTMFo_QyO0xv2Rz5kluhDtinuOE,38
+mact_cli-1.0.0.dist-info/top_level.txt,sha256=2ImG917oaVHlm0nP9oJE-Qrgs-fq_fGWgba2H1f8fpE,4
+mact_cli-1.0.0.dist-info/RECORD,,

mact_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mact_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mact = cli.cli:main

mact_cli-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cli