clipto 0.1.0__py3-none-any.whl

clipto/__init__.py

@@ -0,0 +1,4 @@
+"""Clipto: Instant clipboard, screenshot, and file bridge from browser to terminal."""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

clipto/__main__.py

@@ -0,0 +1,4 @@
+from clipto.cli import main
+
+if __name__ == "__main__":
+    main()

clipto/cli.py

@@ -0,0 +1,174 @@
+import argparse
+import os
+import sys
+import threading
+import time
+import webbrowser
+from pathlib import Path
+from typing import Optional
+
+from clipto import __version__
+from clipto.server import CliptoHTTPServer, CliptoRequestHandler
+from clipto.utils import (
+    find_available_port,
+    get_local_ip,
+    get_tailscale_ip,
+    terminal_hyperlink,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="clipto",
+        description="Instant clipboard, screenshot, and file bridge from browser to terminal.",
+    )
+    parser.add_argument(
+        "-v", "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "-p", "--port",
+        type=int,
+        default=8765,
+        help="Port to listen on (default: 8765, auto-increments if occupied; use 0 for random).",
+    )
+    parser.add_argument(
+        "--no-hunt",
+        action="store_true",
+        help="Disable automatic port hunting if specified port is in use.",
+    )
+    parser.add_argument(
+        "-d", "--dir",
+        type=Path,
+        default=Path("."),
+        help="Target directory where files will be saved (default: current directory).",
+    )
+    parser.add_argument(
+        "-1", "--once",
+        action="store_true",
+        help="One-shot mode: exit immediately after receiving an upload and print saved file path(s).",
+    )
+    parser.add_argument(
+        "-t", "--title",
+        type=str,
+        default=None,
+        help="Custom session title or prompt shown in the web UI header.",
+    )
+    parser.add_argument(
+        "-o", "--open",
+        action="store_true",
+        help="Automatically open the web UI in the default browser on launch.",
+    )
+    parser.add_argument(
+        "--host",
+        type=str,
+        default="0.0.0.0",
+        help="Host address to bind to (default: 0.0.0.0).",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=int,
+        default=None,
+        help="Timeout in seconds (useful with --once to prevent hanging indefinitely).",
+    )
+    return parser
+
+
+def print_banner(
+    port: int,
+    target_dir: Path,
+    title: Optional[str] = None,
+    once: bool = False,
+):
+    local_url = f"http://localhost:{port}"
+    lan_ip = get_local_ip()
+    tailscale_ip = get_tailscale_ip()
+
+    lines = [
+        f"📎 Clipto v{__version__}" + (" [ONE-SHOT MODE]" if once else ""),
+        f"Saving to: {target_dir.resolve()}",
+    ]
+    if title:
+        lines.append(f"Session:   {title}")
+
+    lines.append(f"Local:     {terminal_hyperlink(local_url)}")
+    if lan_ip and lan_ip != "127.0.0.1":
+        lines.append(f"Network:   {terminal_hyperlink(f'http://{lan_ip}:{port}')}")
+    if tailscale_ip:
+        lines.append(f"Tailscale: {terminal_hyperlink(f'http://{tailscale_ip}:{port}')}")
+
+    max_len = max(len(line) for line in lines)
+    border = "─" * (max_len + 4)
+
+    print(f"\n┌{border}┐", file=sys.stderr)
+    for line in lines:
+        padding = " " * (max_len - len(line))
+        print(f"│  {line}{padding}  │", file=sys.stderr)
+    print(f"└{border}┘\n", file=sys.stderr)
+    print("Press Cmd+V or drag files into the browser tab. Press Ctrl+C to stop.\n", file=sys.stderr)
+
+
+def main():
+    parser = build_parser()
+    args = parser.parse_args()
+
+    target_dir = args.dir.resolve()
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    # Determine port
+    if args.no_hunt:
+        port = args.port
+    else:
+        try:
+            port = find_available_port(args.port)
+        except RuntimeError as e:
+            print(f"Error: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    try:
+        server = CliptoHTTPServer(
+            (args.host, port),
+            CliptoRequestHandler,
+            upload_dir=target_dir,
+            title=args.title,
+            once=args.once,
+        )
+    except OSError as e:
+        print(f"Error binding to port {port}: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    print_banner(port, target_dir, title=args.title, once=args.once)
+
+    if args.open:
+        webbrowser.open(f"http://localhost:{port}")
+
+    # Start server thread
+    server_thread = threading.Thread(target=server.serve_forever, daemon=True)
+    server_thread.start()
+
+    start_time = time.time()
+
+    try:
+        while not server.shutdown_event.is_set():
+            if args.timeout and (time.time() - start_time) > args.timeout:
+                print("\nOperation timed out.", file=sys.stderr)
+                server.shutdown()
+                sys.exit(124)
+            time.sleep(0.1)
+
+        # Shutdown triggered (in once mode)
+        server.shutdown()
+
+        # In once mode, output the uploaded file path(s) to stdout
+        for file_path in server.uploaded_files:
+            print(str(file_path.resolve()))
+
+    except KeyboardInterrupt:
+        print("\nStopping Clipto server...", file=sys.stderr)
+        server.shutdown()
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

clipto/server.py

@@ -0,0 +1,186 @@
+import json
+import mimetypes
+import socket
+import threading
+import urllib.parse
+from email.parser import BytesParser
+from email.policy import default
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import List, Optional
+
+from clipto.utils import get_unique_path, sanitize_filename
+
+
+def get_web_dir() -> Path:
+    """Locate the web assets directory."""
+    try:
+        import importlib.resources as pkg_resources
+        return Path(str(pkg_resources.files("clipto").joinpath("web")))
+    except Exception:
+        return Path(__file__).parent / "web"
+
+
+class CliptoHTTPServer(ThreadingHTTPServer):
+    def __init__(
+        self,
+        server_address,
+        RequestHandlerClass,
+        upload_dir: Path,
+        title: Optional[str] = None,
+        once: bool = False,
+    ):
+        super().__init__(server_address, RequestHandlerClass)
+        self.upload_dir = Path(upload_dir).resolve()
+        self.upload_dir.mkdir(parents=True, exist_ok=True)
+        self.title = title
+        self.once = once
+        self.uploaded_files: List[Path] = []
+        self.shutdown_event = threading.Event()
+
+
+class CliptoRequestHandler(BaseHTTPRequestHandler):
+    server: CliptoHTTPServer
+
+    def log_message(self, format, *args):
+        # Suppress verbose standard logging to keep terminal clean
+        pass
+
+    def send_json(self, status: int, data: dict):
+        body = json.dumps(data).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def serve_file(self, file_path: Path):
+        if not file_path.is_file():
+            self.send_error(404, "File Not Found")
+            return
+
+        content_type, _ = mimetypes.guess_type(str(file_path))
+        if file_path.suffix == ".css":
+            content_type = "text/css"
+        elif file_path.suffix == ".js":
+            content_type = "application/javascript"
+
+        content = file_path.read_bytes()
+        self.send_response(200)
+        self.send_header("Content-Type", content_type or "application/octet-stream")
+        self.send_header("Content-Length", str(len(content)))
+        self.end_headers()
+        self.wfile.write(content)
+
+    def do_GET(self):
+        web_dir = get_web_dir()
+        parsed_url = urllib.parse.urlparse(self.path)
+        path = parsed_url.path
+
+        if path in ("/", "/index.html"):
+            self.serve_file(web_dir / "index.html")
+        elif path == "/static/style.css":
+            self.serve_file(web_dir / "style.css")
+        elif path == "/static/app.js":
+            self.serve_file(web_dir / "app.js")
+        elif path == "/api/info":
+            self.send_json(200, {
+                "hostname": socket.gethostname(),
+                "dir": str(self.server.upload_dir),
+                "title": self.server.title,
+                "once": self.server.once,
+            })
+        elif path == "/api/file":
+            query = urllib.parse.parse_qs(parsed_url.query)
+            filename = query.get("name", [None])[0]
+            if not filename:
+                self.send_error(400, "Missing file name")
+                return
+
+            safe_name = sanitize_filename(filename)
+            target = (self.server.upload_dir / safe_name).resolve()
+
+            # Prevent directory traversal attacks
+            try:
+                target.relative_to(self.server.upload_dir)
+            except ValueError:
+                self.send_error(403, "Forbidden")
+                return
+
+            if not target.is_file():
+                self.send_error(404, "File Not Found")
+                return
+
+            self.serve_file(target)
+        elif path == "/api/health":
+            self.send_json(200, {"status": "ok"})
+        else:
+            self.send_error(404, "Not Found")
+
+    def do_POST(self):
+        if self.path != "/api/upload":
+            self.send_error(404, "Not Found")
+            return
+
+        content_type = self.headers.get("Content-Type", "")
+        if not content_type.startswith("multipart/form-data"):
+            self.send_error(400, "Content-Type must be multipart/form-data")
+            return
+
+        try:
+            content_length = int(self.headers.get("Content-Length", 0))
+            if content_length <= 0:
+                self.send_error(400, "Invalid Content-Length")
+                return
+
+            body = self.rfile.read(content_length)
+            raw_data = f"Content-Type: {content_type}\r\n\r\n".encode("utf-8") + body
+            msg = BytesParser(policy=default).parsebytes(raw_data)
+
+            saved_results = []
+            for part in msg.iter_parts():
+                filename = part.get_filename()
+                if not filename:
+                    # Check for note or text parameter
+                    name = part.get_param("name", header="content-disposition")
+                    if name == "note":
+                        text = part.get_payload(decode=True).decode("utf-8", errors="replace").strip()
+                        if text:
+                            target_path = get_unique_path(self.server.upload_dir, "note.txt")
+                            target_path.write_text(text, encoding="utf-8")
+                            saved_results.append({
+                                "name": target_path.name,
+                                "path": str(target_path.resolve()),
+                                "size": target_path.stat().st_size,
+                                "is_image": False,
+                            })
+                            self.server.uploaded_files.append(target_path)
+                    continue
+
+                clean_name = sanitize_filename(filename, default_name="upload.bin")
+                target_path = get_unique_path(self.server.upload_dir, clean_name)
+                payload = part.get_payload(decode=True)
+
+                if payload is not None:
+                    target_path.write_bytes(payload)
+                    is_img = target_path.suffix.lower() in {".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".svg"}
+                    saved_results.append({
+                        "name": target_path.name,
+                        "path": str(target_path.resolve()),
+                        "size": target_path.stat().st_size,
+                        "is_image": is_img,
+                    })
+                    self.server.uploaded_files.append(target_path)
+
+            self.send_json(200, {
+                "status": "ok",
+                "saved_files": saved_results,
+            })
+
+            if self.server.once and self.server.uploaded_files:
+                # Trigger shutdown cleanly in a short delay so the response finishes sending
+                threading.Timer(0.3, self.server.shutdown_event.set).start()
+
+        except Exception as e:
+            self.send_json(500, {"error": str(e)})

clipto/utils.py

@@ -0,0 +1,99 @@
+import os
+import re
+import socket
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional, Tuple
+
+
+def find_available_port(preferred_port: int = 8765, max_attempts: int = 50) -> int:
+    """
+    Find an available TCP port.
+    If preferred_port is 0, let the OS allocate an ephemeral port.
+    Otherwise, check preferred_port up to preferred_port + max_attempts.
+    """
+    if preferred_port == 0:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.bind(("", 0))
+            return s.getsockname()[1]
+
+    for port in range(preferred_port, preferred_port + max_attempts):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            try:
+                s.bind(("", port))
+                return port
+            except OSError:
+                continue
+
+    raise RuntimeError(f"No available port found in range {preferred_port} - {preferred_port + max_attempts}")
+
+
+def get_local_ip() -> Optional[str]:
+    """Determine the LAN IP address of this machine."""
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
+            s.settimeout(0.5)
+            # Doesn't actually send packets, but prompts OS to select route
+            s.connect(("8.8.8.8", 80))
+            return s.getsockname()[0]
+    except Exception:
+        return None
+
+
+def get_tailscale_ip() -> Optional[str]:
+    """Detect Tailscale IPv4 if available."""
+    try:
+        result = subprocess.run(
+            ["tailscale", "ip", "-4"],
+            capture_output=True,
+            text=True,
+            timeout=1,
+            check=False,
+        )
+        if result.returncode == 0:
+            ip = result.stdout.strip().split("\n")[0]
+            if ip.startswith("100."):
+                return ip
+    except Exception:
+        pass
+    return None
+
+
+def sanitize_filename(filename: str, default_name: str = "upload") -> str:
+    """Sanitize uploaded filenames to prevent path traversal and unsafe characters."""
+    filename = os.path.basename(filename).strip()
+    # Remove null bytes and control chars
+    filename = re.sub(r"[\x00-\x1f\x7f]", "", filename)
+    # Replace unsafe characters
+    filename = re.sub(r'[\\/:*?"<>|]', "_", filename)
+    return filename or default_name
+
+
+def get_unique_path(directory: Path, filename: str) -> Path:
+    """
+    Ensure the path does not overwrite an existing file.
+    e.g., photo.png -> photo (1).png -> photo (2).png
+    """
+    target = directory / filename
+    if not target.exists():
+        return target
+
+    stem = target.stem
+    suffix = target.suffix
+    counter = 1
+
+    while True:
+        candidate = directory / f"{stem} ({counter}){suffix}"
+        if not candidate.exists():
+            return candidate
+        counter += 1
+
+
+def terminal_hyperlink(url: str, text: Optional[str] = None) -> str:
+    """Return an OSC 8 terminal hyperlink if terminal is interactive."""
+    display_text = text or url
+    if sys.stdout.isatty():
+        return f"\033]8;;{url}\033\\{display_text}\033]8;;\033\\"
+    return display_text