transmute-cli 0.2.3a0__py3-none-any.whl

transmute/iphone.py

@@ -0,0 +1,247 @@
+"""Synchronous, bounded AFC access to Spotify's vended Documents directory."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from collections.abc import Iterator
+from contextlib import contextmanager, suppress
+from typing import BinaryIO
+
+_BUNDLE_ID = "com.spotify.client"
+_DOCUMENTS_ROOT = "/Documents"
+_CHUNK_SIZE = 1024 * 1024
+_DEADLINE_SECONDS = 20.0
+_MAX_ENTRIES = 20_000
+_MAX_DEPTH = 32
+_MAX_PATH_LENGTH = 1024
+_TEMP_COMPONENT = re.compile(r"\.transmute-sync-[0-9a-f]{32}\.partial\Z")
+
+
+def _sync_error(message: str, cause: BaseException | None = None) -> Exception:
+    from .sync import SyncError
+
+    error = SyncError(message)
+    if cause is not None:
+        error.__cause__ = cause
+    return error
+
+
+def _safe_relative(path: str) -> str:
+    if (
+        not isinstance(path, str)
+        or not path
+        or len(path) > _MAX_PATH_LENGTH
+        or path.startswith("/")
+        or "\\" in path
+        or "\x00" in path
+        or any(part in ("", ".", "..") for part in path.split("/"))
+    ):
+        raise _sync_error("Phone file path is unsafe; preview the phone again.")
+    return path
+
+
+def _remote_path(path: str) -> str:
+    return f"{_DOCUMENTS_ROOT}/{_safe_relative(path)}"
+
+
+def _is_hidden_or_partial(path: str) -> bool:
+    parts = path.split("/")
+    return any(part.startswith(".") for part in parts) or any(
+        part.lower().endswith((".part", ".partial", ".tmp", ".temp")) for part in parts
+    )
+
+
+def _is_owned_temp(path: str) -> bool:
+    return "/" not in path and bool(_TEMP_COMPONENT.fullmatch(path))
+
+
+class _PhoneStore:
+    def __init__(self, loop: asyncio.AbstractEventLoop, lockdown: object, service: object, device_id: str, device_name: str) -> None:
+        self.device_id = device_id
+        self.device_name = device_name
+        self._loop = loop
+        self._lockdown = lockdown
+        self._service = service
+
+    def _run(self, awaitable: object):
+        try:
+            return self._loop.run_until_complete(asyncio.wait_for(awaitable, timeout=_DEADLINE_SECONDS))
+        except asyncio.TimeoutError as exc:
+            raise _sync_error("iPhone USB operation timed out; unlock the phone and retry.", exc) from exc
+        except Exception as exc:
+            from pymobiledevice3.exceptions import AfcFileNotFoundError
+
+            from .sync import SyncError
+
+            if isinstance(exc, (AfcFileNotFoundError, FileNotFoundError, SyncError, FileExistsError)):
+                raise
+            raise _sync_error("iPhone USB operation failed; unlock and trust the phone, then retry.", exc) from exc
+
+    def _check_exists(self, path: str) -> bool:
+        from pymobiledevice3.exceptions import AfcFileNotFoundError
+
+        try:
+            self._run(self._service.stat(_remote_path(path)))
+            return True
+        except (AfcFileNotFoundError, FileNotFoundError):
+            return False
+
+    def list_files(self) -> list[str]:
+        found: list[str] = []
+        visited = 0
+
+        def walk(relative_directory: str, remote_directory: str, depth: int) -> None:
+            nonlocal visited
+            if depth > _MAX_DEPTH:
+                raise _sync_error("Spotify Documents is nested too deeply to scan safely.")
+            names = self._run(self._service.listdir(remote_directory))
+            for name in names:
+                if not isinstance(name, str) or name in ("", ".", "..") or "/" in name or "\\" in name or "\x00" in name:
+                    raise _sync_error("Phone returned an unsafe directory entry; scan stopped.")
+                relative = f"{relative_directory}/{name}" if relative_directory else name
+                relative = _safe_relative(relative)
+                visited += 1
+                if visited > _MAX_ENTRIES:
+                    raise _sync_error("Spotify Documents contains too many entries to scan safely.")
+                if _is_hidden_or_partial(relative):
+                    continue
+                absolute = f"{remote_directory.rstrip('/')}/{name}"
+                try:
+                    metadata = self._run(self._service.stat(absolute))
+                except FileNotFoundError:
+                    continue
+                kind = metadata.get("st_ifmt")
+                if kind == "S_IFDIR":
+                    walk(relative, absolute, depth + 1)
+                elif kind == "S_IFREG" and relative.lower().endswith(".mp3"):
+                    found.append(relative)
+
+        walk("", _DOCUMENTS_ROOT, 0)
+        return found
+
+    def exists(self, relative_path: str) -> bool:
+        return self._check_exists(relative_path)
+
+    def read_to(self, relative_path: str, sink: BinaryIO) -> None:
+        handle = self._run(self._service.fopen(_remote_path(relative_path), "r"))
+        try:
+            while True:
+                chunk = self._run(self._service.fread(handle, _CHUNK_SIZE))
+                if not chunk:
+                    break
+                sink.write(chunk)
+        finally:
+            self._run(self._service.fclose(handle))
+
+    def write_from(self, relative_path: str, source: BinaryIO) -> None:
+        relative_path = _safe_relative(relative_path)
+        if not _is_owned_temp(relative_path):
+            raise _sync_error("Phone writes are limited to Transmute-owned temporary files.")
+        handle = self._run(self._service.fopen(_remote_path(relative_path), "w"))
+        try:
+            while True:
+                chunk = source.read(_CHUNK_SIZE)
+                if not chunk:
+                    break
+                self._run(self._service.fwrite(handle, chunk))
+        finally:
+            self._run(self._service.fclose(handle))
+
+    def publish(self, temporary_path: str, destination_path: str) -> None:
+        temporary_path = _safe_relative(temporary_path)
+        destination_path = _safe_relative(destination_path)
+        if not _is_owned_temp(temporary_path):
+            raise _sync_error("Phone publish source is not a Transmute temporary file.")
+        if self._check_exists(destination_path):
+            raise FileExistsError(destination_path)
+        try:
+            from pymobiledevice3.services.afc import AfcLinkType
+
+            self._run(
+                self._service.link(
+                    _remote_path(temporary_path),
+                    _remote_path(destination_path),
+                    type_=AfcLinkType.HARDLINK,
+                )
+            )
+        except FileExistsError:
+            raise
+        except Exception as exc:
+            from pymobiledevice3.services.afc import AfcError
+
+            from .sync import SyncError
+
+            if isinstance(exc, SyncError) and getattr(exc.__cause__, "status", None) == AfcError.OBJECT_EXISTS:
+                raise FileExistsError(destination_path) from exc
+            raise _sync_error("This iPhone cannot publish files atomically; no file was replaced.", exc) from exc
+        self.remove(temporary_path)
+
+    def remove(self, relative_path: str) -> None:
+        relative_path = _safe_relative(relative_path)
+        if not _is_owned_temp(relative_path):
+            raise _sync_error("Phone cleanup is limited to Transmute-owned temporary files.")
+        self._run(self._service.rm_single(_remote_path(relative_path)))
+
+
+@contextmanager
+def open_spotify(device_id: str | None = None) -> Iterator[_PhoneStore]:
+    """Open exactly one trusted USB iPhone and vend Spotify Documents only."""
+    try:
+        from pymobiledevice3.lockdown import create_using_usbmux
+        from pymobiledevice3.services.house_arrest import HouseArrestService
+        from pymobiledevice3.usbmux import list_devices
+    except ImportError as exc:
+        raise _sync_error("pymobiledevice3 is missing; reinstall Transmute to restore its iPhone sync support.", exc) from exc
+
+    loop = asyncio.new_event_loop()
+    lockdown = None
+    service = None
+    try:
+        try:
+            devices = loop.run_until_complete(asyncio.wait_for(list_devices(), timeout=_DEADLINE_SECONDS))
+        except asyncio.TimeoutError as exc:
+            raise _sync_error("iPhone USB discovery timed out; connect and unlock the phone, then retry.", exc) from exc
+        except Exception as exc:
+            raise _sync_error("Could not discover iPhones over USB; reconnect the phone and retry.", exc) from exc
+        devices = [device for device in devices if device.is_usb]
+        if device_id is not None:
+            devices = [device for device in devices if device.serial == device_id]
+            if not devices:
+                raise _sync_error("The planned iPhone is not connected over USB; reconnect it and preview again.")
+            if len(devices) != 1:
+                raise _sync_error("The planned iPhone was found more than once; reconnect it and preview again.")
+        elif not devices:
+            raise _sync_error("No iPhone is connected by USB; connect and unlock your phone, then retry.")
+        elif len(devices) != 1:
+            raise _sync_error("More than one iPhone is connected; disconnect the other phones and retry.")
+        device = devices[0]
+        try:
+            lockdown = loop.run_until_complete(
+                asyncio.wait_for(
+                    create_using_usbmux(device.serial, autopair=False, connection_type="USB"),
+                    timeout=_DEADLINE_SECONDS,
+                )
+            )
+            service = loop.run_until_complete(
+                asyncio.wait_for(
+                    HouseArrestService.create(lockdown, bundle_id=_BUNDLE_ID, documents_only=True),
+                    timeout=_DEADLINE_SECONDS,
+                )
+            )
+        except asyncio.TimeoutError as exc:
+            raise _sync_error("Opening Spotify over USB timed out; unlock and reconnect the phone, then retry.", exc) from exc
+        except Exception as exc:
+            message = "Unlock and trust this iPhone, install Spotify, then reconnect and retry."
+            raise _sync_error(message, exc) from exc
+        name = str(lockdown.all_values.get("DeviceName") or "iPhone")[:100]
+        store = _PhoneStore(loop, lockdown, service, device.serial, name)
+        yield store
+    finally:
+        if service is not None:
+            with suppress(Exception):
+                loop.run_until_complete(asyncio.wait_for(service.close(), timeout=_DEADLINE_SECONDS))
+        if lockdown is not None:
+            with suppress(Exception):
+                loop.run_until_complete(asyncio.wait_for(lockdown.close(), timeout=_DEADLINE_SECONDS))
+        loop.close()

transmute/keys.py

@@ -0,0 +1,152 @@
+"""Key bindings. Takes the App for state access; owns no state."""
+
+from __future__ import annotations
+
+import time
+
+from prompt_toolkit.filters import Condition, has_completions, has_focus
+from prompt_toolkit.key_binding import KeyBindings
+
+
+def _exit_shortcut() -> str:
+    return "CTRL+C"
+
+
+def build_key_bindings(app) -> KeyBindings:
+    kb = KeyBindings()
+    # Main input actions remain live while help and the folder editor are shown.
+    no_overlay = Condition(
+        lambda: app.modal is None and app.dir_picker is None and not app.help_open and not app.sync_open
+    )
+    has_actionable = Condition(lambda: bool(app._actionable())) & no_overlay
+    has_selection = Condition(app.has_selection)
+    sel_is_err = (
+        Condition(lambda: app._sel_kind() == "err" and not app.input_buffer.text)
+        & no_overlay
+    )
+    picker_confirm = Condition(
+        lambda: app.dir_picker is not None and app.dir_picker.stage == "confirm"
+    )
+    dir_focused = has_focus(app.dir_buffer)
+    sync_focused = Condition(
+        lambda: app.sync_open
+        and app.app.layout.current_control is app.sync_control
+    )
+
+    @kb.add("up", filter=has_actionable)
+    def _(event):
+        app._move_sel(-1)
+
+    @kb.add("up", filter=sync_focused)
+    def _(event):
+        app.sync_move(-1)
+
+    @kb.add("down", filter=sync_focused)
+    def _(event):
+        app.sync_move(1)
+
+    @kb.add("enter", filter=sync_focused, eager=True)
+    def _(event):
+        app.sync_toggle()
+
+    @kb.add("a", filter=sync_focused, eager=True)
+    def _(event):
+        app.sync_select(True)
+
+    @kb.add("A", filter=sync_focused, eager=True)
+    def _(event):
+        app.sync_select(False)
+
+    @kb.add("down", filter=has_actionable & has_selection)
+    def _(event):
+        app._move_sel(1)
+
+    @kb.add("y", filter=picker_confirm & dir_focused)
+    def _(event):
+        app._dir_confirm_create()
+
+    @kb.add("n", filter=picker_confirm & dir_focused)
+    def _(event):
+        app._dir_decline_create()
+
+    @kb.add("escape", eager=True)
+    def _(event):
+        if app.sync_open:
+            app.sync_back()
+            return
+        if app.dir_picker is not None:
+            app.close_dir_picker()
+            return
+        if app.help_open:
+            app.close_help()
+            return
+        if app.modal:
+            app.close_modal()
+            return
+        app.clear_selection()
+
+    @kb.add("enter", filter=sel_is_err & has_focus(app.input_buffer))
+    def _(event):
+        app._retry_selected()
+
+    @kb.add("c-c")
+    def _(event):
+        now = time.monotonic()
+        if app.dir_picker is not None:
+            app.close_dir_picker()
+            return
+        if app.sync_open:
+            app.sync_back()
+            return
+        if app.help_open:
+            app.close_help()
+            return
+        if app.has_selection():
+            app.clear_selection()
+            app.clear_input_notice()
+            app._last_ctrl_c = now
+            return
+        if app.input_buffer.text:
+            app.input_buffer.reset()
+            app.clear_input_notice()
+            app._last_ctrl_c = now
+            return
+        if now - app._last_ctrl_c <= 2.0:
+            event.app.exit()
+        else:
+            app._last_ctrl_c = now
+            with app.lock:
+                busy = len(app.active) + app.queued
+            note = (
+                f" ({busy} job{'s' if busy != 1 else ''} still running)" if busy else ""
+            )
+            app.show_input_notice(
+                "class:input.warn",
+                f"press {_exit_shortcut()} again to exit{note}",
+                duration=2.0,
+            )
+
+    @kb.add("c-d")
+    def _(event):
+        event.app.exit()
+
+    @kb.add(
+        "tab",
+        filter=Condition(lambda: app.dir_picker is not None) & ~has_completions,
+    )
+    def _(event):
+        app.toggle_dir_focus()
+
+    @kb.add("s-tab", filter=Condition(lambda: app.dir_picker is not None))
+    def _(event):
+        app.toggle_dir_focus()
+
+    @kb.add("tab", filter=Condition(lambda: app.sync_open) & ~has_completions)
+    def _(event):
+        app.toggle_sync_focus()
+
+    @kb.add("s-tab", filter=Condition(lambda: app.sync_open))
+    def _(event):
+        app.toggle_sync_focus()
+
+    return kb

transmute/layout.py

@@ -0,0 +1,125 @@
+"""Window arrangement. Takes the App for state/render callables; owns no state."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from prompt_toolkit.buffer import Buffer
+from prompt_toolkit.filters import Condition
+from prompt_toolkit.history import FileHistory
+from prompt_toolkit.layout import (
+    ConditionalContainer,
+    Float,
+    FloatContainer,
+    HSplit,
+    Layout,
+    ScrollablePane,
+    Window,
+)
+from prompt_toolkit.layout.controls import BufferControl, FormattedTextControl
+from prompt_toolkit.layout.dimension import Dimension
+from prompt_toolkit.layout.menus import CompletionsMenu
+
+from .style import HINT_PLACEHOLDER
+from .widgets import HomeDirCompleter, PlaceholderProcessor, ScrollableHelpControl
+
+
+def build_layout(app, history_file: Path) -> Layout:
+    """Create buffers + windows on `app` and return the assembled Layout."""
+
+    app.input_buffer = Buffer(
+        history=FileHistory(str(history_file)),
+        multiline=False,
+        accept_handler=app._accept,
+        enable_history_search=True,
+    )
+    app.dir_buffer = Buffer(
+        multiline=False,
+        accept_handler=app._accept,
+        completer=HomeDirCompleter(
+            lambda: app.dir_picker is not None and app.dir_picker.stage == "input"
+        ),
+        complete_while_typing=True,
+    )
+    app.hint_buffer = Buffer(multiline=False, accept_handler=app._accept_hint)
+
+    input_window = Window(
+        BufferControl(
+            app.input_buffer,
+            input_processors=[PlaceholderProcessor(app._input_placeholder)],
+        ),
+        height=1,
+        get_line_prefix=lambda _line_no, _wrap_count: app._input_prefix(),
+    )
+    hint_window = Window(
+        BufferControl(
+            app.hint_buffer,
+            input_processors=[PlaceholderProcessor(HINT_PLACEHOLDER)],
+        ),
+        height=1,
+        get_line_prefix=lambda _line_no, _wrap_count: [("class:prompt", "      ↳ ")],
+    )
+    dir_window = Window(
+        BufferControl(
+            app.dir_buffer,
+            input_processors=[PlaceholderProcessor(app._dir_placeholder)],
+        ),
+        height=1,
+        get_line_prefix=lambda _line_no, _wrap_count: app._dir_prefix(),
+    )
+    app.help_pane = ScrollablePane(
+        Window(
+            ScrollableHelpControl(app._render_help, app.scroll_help), wrap_lines=True
+        )
+    )
+    app.sync_control = ScrollableHelpControl(app._render_sync, app.sync_scroll, focusable=True)
+    app.sync_pane = ScrollablePane(
+        Window(app.sync_control, wrap_lines=False), keep_cursor_visible=False
+    )
+    normal_content = Condition(lambda: not app.help_open and not app.sync_open)
+
+    root = HSplit(
+        [
+            Window(FormattedTextControl(app._render_header), height=4),
+            Window(height=1, char="─", style="class:rule"),
+            ConditionalContainer(
+                Window(
+                    FormattedTextControl(app._render_above),
+                    height=app._above_height,
+                    wrap_lines=False,
+                ),
+                filter=normal_content,
+            ),
+            ConditionalContainer(
+                hint_window,
+                filter=normal_content & Condition(lambda: app._sel_kind() == "hint"),
+            ),
+            ConditionalContainer(
+                Window(
+                    FormattedTextControl(app._render_below),
+                    height=Dimension(weight=1),
+                    wrap_lines=False,
+                ),
+                filter=normal_content,
+            ),
+            ConditionalContainer(app.help_pane, filter=Condition(lambda: app.help_open)),
+            ConditionalContainer(app.sync_pane, filter=Condition(lambda: app.sync_open)),
+            Window(height=1, char="─", style="class:rule"),
+            ConditionalContainer(
+                dir_window, filter=Condition(lambda: app.dir_picker is not None)
+            ),
+            input_window,
+            Window(FormattedTextControl(app._status_line), height=1),
+        ]
+    )
+    root = FloatContainer(
+        root,
+        floats=[
+            Float(
+                xcursor=True,
+                ycursor=True,
+                content=CompletionsMenu(max_height=8, scroll_offset=1),
+            )
+        ],
+    )
+    return Layout(root, focused_element=input_window)

transmute/main.py

@@ -0,0 +1,38 @@
+"""Entry point: thin wiring only."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .app import App
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="transmute",
+        description="Convert YouTube or SoundCloud links into rich MP3s.",
+        epilog=(
+            "Run with no arguments to open the interface, then paste links. "
+            "Type /help inside it for the command reference."
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"transmute {__version__}",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Parse argv, then hand control to the interface.
+
+    Installed as a console script, so `--version` and `--help` must answer and
+    exit before the full-screen interface takes over the terminal.
+    """
+    _build_parser().parse_args(argv)
+    sys.stdout.write("\x1b]0;Transmute\x07")  # terminal tab title
+    sys.stdout.flush()
+    App().run()

transmute/settings.py

@@ -0,0 +1,114 @@
+"""Durable, prompt-toolkit-independent user settings.
+
+Settings resolve in one order: a runtime command in the current session
+overrides the value read from this file, which overrides the built-in defaults
+in `Settings`. There is no environment layer for output directory or quality
+yet; a new source belongs in this resolution order rather than in scattered
+`os.environ` reads.
+
+The file is versioned JSON written atomically (temporary file plus
+`os.replace`) so an interrupted write cannot corrupt the only saved copy.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+from .config import QUALITIES, SETTINGS_VERSION, Settings
+
+
+class SettingsStoreError(RuntimeError):
+    """Saved settings could not be read or written safely."""
+
+
+class SettingsStore:
+    """Reads and writes the persisted `Settings` record as versioned JSON."""
+
+    def __init__(self, path: Path | str) -> None:
+        self.path = Path(path).expanduser()
+
+    def load(self) -> Settings:
+        """Return saved settings, or defaults when nothing is stored yet.
+
+        A missing file is the normal first-run case and yields defaults. A
+        present-but-unreadable or schema-incompatible file raises
+        `SettingsStoreError` so the caller can warn and fall back to defaults
+        without overwriting the unrecognized file.
+        """
+        try:
+            raw = self.path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return Settings()
+        except OSError as exc:
+            raise SettingsStoreError(
+                f"Could not read settings at {self.path}: {exc}"
+            ) from exc
+
+        try:
+            data = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise SettingsStoreError(
+                f"Settings at {self.path} contain malformed JSON: {exc}"
+            ) from exc
+        if not isinstance(data, dict):
+            raise SettingsStoreError(f"Settings at {self.path} are not a JSON object")
+
+        version = data.get("version")
+        if version != SETTINGS_VERSION:
+            raise SettingsStoreError(
+                f"Settings at {self.path} use unsupported schema version "
+                f"{version!r}; expected {SETTINGS_VERSION}"
+            )
+
+        return Settings(
+            out_dir=_resolve_out_dir(data.get("out_dir")),
+            quality=_resolve_quality(data.get("quality")),
+        )
+
+    def save(self, settings: Settings) -> None:
+        """Persist settings atomically with owner-only permissions."""
+        payload = {
+            "version": SETTINGS_VERSION,
+            "out_dir": str(settings.out_dir),
+            "quality": settings.quality,
+        }
+        text = json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+        try:
+            self.path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+            descriptor, tmp_name = tempfile.mkstemp(
+                dir=self.path.parent, prefix=".settings-", suffix=".tmp"
+            )
+            tmp_path = Path(tmp_name)
+            try:
+                with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+                    handle.write(text)
+                    handle.flush()
+                    os.fsync(handle.fileno())
+                tmp_path.chmod(0o600)
+                os.replace(tmp_path, self.path)
+            except OSError:
+                tmp_path.unlink(missing_ok=True)
+                raise
+        except OSError as exc:
+            raise SettingsStoreError(
+                f"Could not save settings at {self.path}: {exc}"
+            ) from exc
+
+
+def _resolve_out_dir(value: object) -> Path:
+    if value is None:
+        return Settings().out_dir
+    if not isinstance(value, str) or not value:
+        raise SettingsStoreError(f"invalid output directory: {value!r}")
+    return Path(value).expanduser()
+
+
+def _resolve_quality(value: object) -> str:
+    if value is None:
+        return Settings().quality
+    if value not in QUALITIES:
+        raise SettingsStoreError(f"unsupported quality: {value!r}")
+    return value