mac-android-file-transfer 0.1.0__py3-none-any.whl

mac_android_file_transfer-0.1.0.dist-info/METADATA

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: mac-android-file-transfer
+Version: 0.1.0
+Summary: macOS CLI wrapper around go-mtpfs for Android file transfer
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# mac-android-file-transfer
+
+`maft` is a macOS CLI wrapper around
+[`github.com/ganeshrvel/go-mtpfs`](https://github.com/ganeshrvel/go-mtpfs).
+It mounts Android MTP storage to a local folder, then provides explicit `cp`,
+`mv`, and `rm` commands over that mounted filesystem.
+
+## Requirements
+
+- macOS
+- macFUSE
+- `go-mtpfs` available in `PATH`
+- `diskutil` or `/sbin/umount` for unmounting
+
+Run:
+
+```sh
+maft doctor
+```
+
+## Usage
+
+```sh
+maft mount ~/Android
+maft cp --mount ~/Android ~/Downloads/photo.jpg DCIM/photo.jpg
+maft cp --mount ~/Android -r DCIM ~/Desktop/DCIM
+maft mv --mount ~/Android DCIM/photo.jpg Pictures/photo.jpg
+maft rm --mount ~/Android Pictures/photo.jpg
+maft rm --mount ~/Android -r Pictures/old-folder
+maft unmount ~/Android
+```
+
+For file commands, absolute paths and `~/...` paths are treated as host paths.
+Other paths are treated as Android paths relative to the mount folder.

mac_android_file_transfer-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+maft/__init__.py,sha256=RiFAM3tBbJZXGnZOEnPWWfIhC0F-bqMV9HDHs0roBBI,89
+maft/cli.py,sha256=HftSme0oL99FP-s6NvRFd8wnbeWTI87w1GyPXIgjs9U,12839
+mac_android_file_transfer-0.1.0.dist-info/METADATA,sha256=DUL40w_Gte-zuRaJYNVxWpQthdoi_1TvWn4QvWChNYg,1103
+mac_android_file_transfer-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+mac_android_file_transfer-0.1.0.dist-info/entry_points.txt,sha256=ZvOFMVVPE6mF03L3ufUy-iCRyTJWOgTDYK7uPyNNGpQ,39
+mac_android_file_transfer-0.1.0.dist-info/RECORD,,

mac_android_file_transfer-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mac_android_file_transfer-0.1.0.dist-info/entry_points.txt

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

maft/__init__.py

@@ -0,0 +1,5 @@
+"""macOS Android file transfer CLI."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

maft/cli.py

@@ -0,0 +1,385 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import cast
+
+from maft import __version__
+
+APP_NAME = "maft"
+DEFAULT_STATE_DIR = Path.home() / "Library" / "Application Support" / APP_NAME
+DEFAULT_MACFUSE_PATHS = (
+    Path("/Library/Filesystems/macfuse.fs"),
+    Path("/Library/Filesystems/osxfuse.fs"),
+)
+
+
+@dataclass(frozen=True)
+class MountRecord:
+    mountpoint: str
+    pid: int
+    command: list[str]
+    created_at: float
+
+
+class CliError(Exception):
+    pass
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except CliError as exc:
+        print(f"maft: {exc}", file=sys.stderr)
+        return 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="maft",
+        description="Mount and manage Android MTP files on macOS via go-mtpfs.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    doctor = subparsers.add_parser("doctor", help="check local dependencies")
+    doctor.set_defaults(func=cmd_doctor)
+
+    mount = subparsers.add_parser("mount", help="mount an Android device")
+    mount.add_argument("mountpoint")
+    mount.add_argument("--dev", help="go-mtpfs device selector")
+    mount.add_argument("--storage", help="go-mtpfs storage selector")
+    mount.add_argument("--android", dest="android", action="store_true", default=True)
+    mount.add_argument("--no-android", dest="android", action="store_false")
+    mount.add_argument("--allow-other", action="store_true")
+    mount.add_argument("--debug", action="store_true")
+    mount.add_argument("--usb-timeout", type=int, help="go-mtpfs USB timeout")
+    mount.set_defaults(func=cmd_mount)
+
+    unmount = subparsers.add_parser("unmount", help="unmount an Android mount folder")
+    unmount.add_argument("mountpoint")
+    unmount.set_defaults(func=cmd_unmount)
+
+    cp = subparsers.add_parser("cp", help="copy files to, from, or within a mounted device")
+    add_mount_arg(cp)
+    cp.add_argument("-r", "--recursive", action="store_true", help="copy directories recursively")
+    cp.add_argument("src")
+    cp.add_argument("dst")
+    cp.set_defaults(func=cmd_cp)
+
+    mv = subparsers.add_parser("mv", help="move files to, from, or within a mounted device")
+    add_mount_arg(mv)
+    mv.add_argument("src")
+    mv.add_argument("dst")
+    mv.set_defaults(func=cmd_mv)
+
+    rm = subparsers.add_parser("rm", help="remove files from a mounted device")
+    add_mount_arg(rm)
+    rm.add_argument("-r", "--recursive", action="store_true", help="remove directories recursively")
+    rm.add_argument("paths", nargs="+")
+    rm.set_defaults(func=cmd_rm)
+
+    return parser
+
+
+def add_mount_arg(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--mount",
+        required=True,
+        dest="mountpoint",
+        help="mounted Android folder",
+    )
+
+
+def cmd_doctor(_args: argparse.Namespace) -> int:
+    checks = [
+        ("go-mtpfs", shutil.which("go-mtpfs") is not None, install_go_mtpfs_help()),
+        ("diskutil", shutil.which("diskutil") is not None, "Provided by macOS."),
+        ("/sbin/umount", Path("/sbin/umount").exists(), "Provided by macOS."),
+        ("macFUSE", macfuse_available(), "Install from https://macfuse.github.io/."),
+    ]
+
+    failed = False
+    for name, ok, help_text in checks:
+        status = "ok" if ok else "missing"
+        print(f"{name}: {status}")
+        if not ok:
+            failed = True
+            print(f"  {help_text}")
+    return 1 if failed else 0
+
+
+def cmd_mount(args: argparse.Namespace) -> int:
+    go_mtpfs = shutil.which("go-mtpfs")
+    if go_mtpfs is None:
+        raise CliError(f"go-mtpfs not found in PATH. {install_go_mtpfs_help()}")
+    if not macfuse_available():
+        raise CliError("macFUSE was not detected. Install it from https://macfuse.github.io/.")
+
+    mountpoint = expand_path(args.mountpoint)
+    if mountpoint.exists() and not mountpoint.is_dir():
+        raise CliError(f"mountpoint exists and is not a directory: {mountpoint}")
+    mountpoint.mkdir(parents=True, exist_ok=True)
+
+    command = [go_mtpfs]
+    if args.dev:
+        command.extend(["-dev", args.dev])
+    if args.storage:
+        command.extend(["-storage", args.storage])
+    if not args.android:
+        command.append("-android=false")
+    if args.allow_other:
+        command.append("-allow-other")
+    if args.debug:
+        command.append("-debug")
+    if args.usb_timeout is not None:
+        command.extend(["-usb-timeout", str(args.usb_timeout)])
+    command.append(str(mountpoint))
+
+    stdout = None if args.debug else subprocess.DEVNULL
+    stderr = None if args.debug else subprocess.DEVNULL
+    process = subprocess.Popen(command, stdout=stdout, stderr=stderr, start_new_session=True)
+    write_mount_record(
+        MountRecord(
+            mountpoint=str(mountpoint),
+            pid=process.pid,
+            command=command,
+            created_at=time.time(),
+        )
+    )
+    print(f"mounted {mountpoint} with go-mtpfs pid {process.pid}")
+    return 0
+
+
+def cmd_unmount(args: argparse.Namespace) -> int:
+    mountpoint = require_dir(expand_path(args.mountpoint), "mountpoint")
+    errors: list[str] = []
+    diskutil = shutil.which("diskutil")
+    if diskutil is not None:
+        result = subprocess.run(
+            [diskutil, "unmount", str(mountpoint)],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode == 0:
+            remove_mount_record(mountpoint)
+            print(f"unmounted {mountpoint}")
+            return 0
+        errors.append(result.stderr.strip() or result.stdout.strip() or "diskutil unmount failed")
+
+    umount = shutil.which("umount") or "/sbin/umount"
+    result = subprocess.run(
+        [umount, str(mountpoint)],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0:
+        remove_mount_record(mountpoint)
+        print(f"unmounted {mountpoint}")
+        return 0
+    errors.append(result.stderr.strip() or result.stdout.strip() or "umount failed")
+
+    joined = "; ".join(error for error in errors if error)
+    raise CliError(f"could not unmount {mountpoint}: {joined}")
+
+
+def cmd_cp(args: argparse.Namespace) -> int:
+    mountpoint = require_mountpoint(args.mountpoint)
+    src = resolve_operation_path(mountpoint, args.src)
+    dst = resolve_operation_path(mountpoint, args.dst)
+
+    if src.path.is_dir():
+        if not args.recursive:
+            raise CliError(f"{src.original} is a directory; pass --recursive")
+        copy_directory(src.path, destination_for_copy(dst.path, src.path.name))
+    else:
+        copy_file(src.path, destination_for_copy(dst.path, src.path.name))
+    return 0
+
+
+def cmd_mv(args: argparse.Namespace) -> int:
+    mountpoint = require_mountpoint(args.mountpoint)
+    src = resolve_operation_path(mountpoint, args.src)
+    dst = resolve_operation_path(mountpoint, args.dst)
+    target = destination_for_copy(dst.path, src.path.name)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(src.path), str(target))
+    return 0
+
+
+def cmd_rm(args: argparse.Namespace) -> int:
+    mountpoint = require_mountpoint(args.mountpoint)
+    for raw_path in args.paths:
+        if is_host_path(raw_path):
+            raise CliError(f"rm only accepts Android-relative paths, got host path: {raw_path}")
+        target = resolve_android_path(mountpoint, raw_path)
+        if target.is_dir():
+            if not args.recursive:
+                raise CliError(f"{raw_path} is a directory; pass --recursive")
+            shutil.rmtree(target)
+        elif target.exists():
+            target.unlink()
+        else:
+            raise CliError(f"path does not exist: {raw_path}")
+    return 0
+
+
+@dataclass(frozen=True)
+class OperationPath:
+    original: str
+    path: Path
+    is_host: bool
+
+
+def resolve_operation_path(mountpoint: Path, value: str) -> OperationPath:
+    if is_host_path(value):
+        return OperationPath(value, expand_path(value), True)
+    return OperationPath(value, resolve_android_path(mountpoint, value), False)
+
+
+def resolve_android_path(mountpoint: Path, value: str) -> Path:
+    if value in {"", "."}:
+        return mountpoint
+    candidate = (mountpoint / value).resolve(strict=False)
+    try:
+        candidate.relative_to(mountpoint)
+    except ValueError as exc:
+        raise CliError(f"Android path escapes mountpoint: {value}") from exc
+    return candidate
+
+
+def is_host_path(value: str) -> bool:
+    return value.startswith("/") or value.startswith("~/") or value == "~"
+
+
+def destination_for_copy(destination: Path, source_name: str) -> Path:
+    if destination.exists() and destination.is_dir():
+        return destination / source_name
+    if str(destination).endswith(os.sep):
+        destination.mkdir(parents=True, exist_ok=True)
+        return destination / source_name
+    return destination
+
+
+def copy_file(src: Path, dst: Path) -> None:
+    if not src.is_file():
+        raise CliError(f"source file does not exist: {src}")
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(src, dst)
+
+
+def copy_directory(src: Path, dst: Path) -> None:
+    if not src.is_dir():
+        raise CliError(f"source directory does not exist: {src}")
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(src, dst, dirs_exist_ok=True)
+
+
+def require_mountpoint(value: str) -> Path:
+    mountpoint = require_dir(expand_path(value), "mountpoint")
+    return mountpoint.resolve(strict=True)
+
+
+def require_dir(path: Path, label: str) -> Path:
+    if not path.exists():
+        raise CliError(f"{label} does not exist: {path}")
+    if not path.is_dir():
+        raise CliError(f"{label} is not a directory: {path}")
+    return path
+
+
+def expand_path(value: str) -> Path:
+    return Path(value).expanduser().resolve(strict=False)
+
+
+def state_dir() -> Path:
+    override = os.environ.get("MAFT_STATE_DIR")
+    return Path(override).expanduser() if override else DEFAULT_STATE_DIR
+
+
+def state_file() -> Path:
+    return state_dir() / "mounts.json"
+
+
+def load_mount_records() -> dict[str, MountRecord]:
+    path = state_file()
+    if not path.exists():
+        return {}
+    data: object = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise CliError(f"invalid state file: {path}")
+    raw_records = cast("dict[object, object]", data)
+    records: dict[str, MountRecord] = {}
+    for mountpoint, record in raw_records.items():
+        if not isinstance(mountpoint, str) or not isinstance(record, dict):
+            continue
+        raw_record = cast("dict[object, object]", record)
+        raw_command = raw_record.get("command")
+        raw_mountpoint = raw_record.get("mountpoint")
+        raw_pid = raw_record.get("pid")
+        raw_created_at = raw_record.get("created_at")
+        if (
+            not isinstance(raw_mountpoint, str)
+            or not isinstance(raw_pid, int)
+            or not isinstance(raw_created_at, int | float)
+            or not isinstance(raw_command, list)
+        ):
+            continue
+        command = cast("list[object]", raw_command)
+        records[mountpoint] = MountRecord(
+            mountpoint=raw_mountpoint,
+            pid=raw_pid,
+            command=[str(part) for part in command],
+            created_at=float(raw_created_at),
+        )
+    return records
+
+
+def save_mount_records(records: dict[str, MountRecord]) -> None:
+    directory = state_dir()
+    directory.mkdir(parents=True, exist_ok=True)
+    state_file().write_text(
+        json.dumps({key: asdict(value) for key, value in records.items()}, indent=2) + "\n",
+        encoding="utf-8",
+    )
+
+
+def write_mount_record(record: MountRecord) -> None:
+    records = load_mount_records()
+    records[record.mountpoint] = record
+    save_mount_records(records)
+
+
+def remove_mount_record(mountpoint: Path) -> None:
+    records = load_mount_records()
+    records.pop(str(mountpoint.resolve(strict=False)), None)
+    save_mount_records(records)
+
+
+def macfuse_available() -> bool:
+    override = os.environ.get("MAFT_MACFUSE_PATHS")
+    paths = [Path(path).expanduser() for path in override.split(os.pathsep)] if override else list(
+        DEFAULT_MACFUSE_PATHS
+    )
+    return any(path.exists() for path in paths)
+
+
+def install_go_mtpfs_help() -> str:
+    return (
+        "Install Go and go-mtpfs, for example: "
+        "brew install go libusb pkg-config && go install github.com/ganeshrvel/go-mtpfs@latest"
+    )
+
+if __name__ == "__main__":
+    raise SystemExit(main())