dosctl 0.1.0__py3-none-any.whl

dosctl/collections/archive_org.py

@@ -0,0 +1,227 @@
+import hashlib
+import re
+import requests
+from pathlib import Path
+from typing import List, Dict, Optional
+import zipfile
+from urllib.parse import quote, unquote
+from tqdm import tqdm
+
+from .base import BaseCollection
+
+class ArchiveOrgCollection(BaseCollection):
+    """
+    Base class for Archive.org collection backends.
+    Handles common functionality like downloading, caching, and parsing.
+    """
+
+    def __init__(self, source: str, cache_dir: str, collection_name: str):
+        super().__init__(source)
+        self.cache_dir = Path(cache_dir)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self.collection_name = collection_name
+        self._games_data: List[Dict] = []
+
+        # The download URL for a file is different from the source URL of the list.
+        # We derive the base download URL from the source URL's item name.
+        # e.g., https://.../items/ITEM_NAME/file.txt -> https://archive.org/download/ITEM_NAME
+        self.item_name = self.source.split("/")[-2]
+        self.download_base_url = f"https://archive.org/download/{self.item_name}"
+
+    def ensure_cache_is_present(self, force_refresh: bool = False) -> None:
+        """
+        Ensures the game list cache exists, downloading it if it's missing or
+        if a refresh is forced.
+        """
+        cache_file = self.cache_dir / "games.txt"
+        if force_refresh or not cache_file.exists():
+            print(f"Downloading game list from {self.source}...")
+            headers = {'User-Agent': 'Mozilla/5.0'}
+            response = requests.get(self.source, headers=headers)
+            response.raise_for_status()
+            with open(cache_file, "w", encoding="utf-8") as f:
+                f.write(response.text)
+            print("✅ Game list refreshed successfully.")
+
+    def load(self, force_refresh: bool = False) -> None:
+        self.ensure_cache_is_present(force_refresh=force_refresh)
+        self._populate_games_data()
+
+    def _parse_filename(self, filename: str) -> Dict:
+        """
+        Parses a filename to extract the year and a clean name.
+        Can be overridden by subclasses for different parsing logic.
+        """
+        name_part = filename.replace(".zip", "")
+        year = None
+
+        # Try to find a year like (1995) in the name
+        match = re.search(r'\(([0-9]{4})\)', name_part)
+        if match:
+            year = match.group(1)
+
+        return {"name": name_part, "year": year}
+
+    def _populate_games_data(self) -> None:
+        cache_file = self.cache_dir / "games.txt"
+        if not cache_file.exists():
+            return
+
+        self._games_data = []
+        with open(cache_file, "r", encoding="utf-8") as f:
+            content = f.read()
+
+        zip_hrefs = re.findall(r'href="(.+?\.zip)"', content)
+
+        for href in zip_hrefs:
+            encoded_path = href.split("/")[-1]
+            full_path = unquote(encoded_path)
+
+            filename_with_ext = Path(full_path).name
+
+            # Use the parser (can be overridden by subclasses)
+            parsed_details = self._parse_filename(filename_with_ext)
+
+            # The game's unique ID is a short, stable hash of its full path.
+            # This prevents collisions and ensures the ID is always the same.
+            game_hash = hashlib.sha1(full_path.encode()).hexdigest()
+            game_id = game_hash[:8]
+
+            self._games_data.append({
+                "id": game_id,
+                "name": parsed_details["name"],
+                "year": parsed_details["year"],
+                "full_path": full_path,
+            })
+
+    def get_games(self) -> List[Dict]:
+        if not self._games_data:
+            self._populate_games_data()
+        return self._games_data
+
+    def _find_game(self, game_id: str) -> Optional[Dict]:
+        if not self._games_data:
+            self._populate_games_data()
+        for game in self._games_data:
+            if game["id"] == game_id:
+                return game
+        return None
+
+    def get_download_url(self, game_id: str) -> Optional[str]:
+        """
+        Constructs the download URL for a specific game.
+        Can be overridden by subclasses for different URL patterns.
+        """
+        game = self._find_game(game_id)
+        if not game:
+            return None
+
+        # The download URL is constructed from the base item name and the full path
+        encoded_full_path = quote(game["full_path"])
+        return self._build_download_url(encoded_full_path)
+
+    def _build_download_url(self, encoded_full_path: str) -> str:
+        """
+        Builds the actual download URL. Override this in subclasses for different URL patterns.
+        """
+        raise NotImplementedError("Subclasses must implement _build_download_url")
+
+    def download_game(self, game_id: str, destination: str, force: bool = False) -> None:
+        download_url = self.get_download_url(game_id)
+        if not download_url:
+            raise FileNotFoundError(f"Game with ID '{game_id}' not found.")
+
+        game = self._find_game(game_id)
+        destination_path = Path(destination)
+        destination_path.mkdir(parents=True, exist_ok=True)
+
+        filename = game["name"] + ".zip"
+        local_zip_path = destination_path / filename
+
+        if local_zip_path.exists() and not force:
+            print(f"'{filename}' already exists in '{destination_path}'. Use --force to overwrite.")
+            return local_zip_path
+
+        headers = {'User-Agent': 'Mozilla/5.0'}
+
+        # Use a try...except block for more specific error handling
+        try:
+            with requests.get(download_url, headers=headers, stream=True) as r:
+                r.raise_for_status()
+
+                total_size = int(r.headers.get('content-length', 0))
+
+                with tqdm.wrapattr(open(local_zip_path, "wb"), "write",
+                                 miniters=1,
+                                 total=total_size,
+                                 desc=f"Downloading '{filename}'") as fout:
+                    for chunk in r.iter_content(chunk_size=8192):
+                        fout.write(chunk)
+
+            print(f"Successfully downloaded '{filename}'")
+        except requests.exceptions.RequestException as e:
+            print(f"\nError downloading '{filename}': {e}")
+            # Clean up partially downloaded file
+            if local_zip_path.exists():
+                local_zip_path.unlink()
+            return None
+
+        return local_zip_path
+
+    def unzip_game(self, game_id: str, download_path: Path, install_path: Path) -> None:
+        """
+        Unzips a downloaded game to a specified installation directory.
+        """
+        game = self._find_game(game_id)
+        if not game:
+            raise FileNotFoundError(f"Game with ID '{game_id}' not found.")
+
+        zip_filename = game["name"] + ".zip"
+        zip_filepath = download_path / zip_filename
+
+        if not zip_filepath.exists():
+            raise FileNotFoundError(f"Downloaded game zip not found at '{zip_filepath}'")
+
+        print(f"Unzipping '{zip_filename}' to '{install_path}'...")
+        with zipfile.ZipFile(zip_filepath, 'r') as zip_ref:
+            zip_ref.extractall(install_path)
+        print("Unzip complete.")
+
+
+class TotalDOSCollectionRelease14(ArchiveOrgCollection):
+    """
+    Specific implementation for Total DOS Collection Release 14.
+    """
+
+    def __init__(self, source: str, cache_dir: str):
+        super().__init__(source, cache_dir, "Total DOS Collection Release 14")
+
+    def _build_download_url(self, encoded_full_path: str) -> str:
+        """
+        Builds the download URL specific to TDC Release 14 structure.
+        """
+        return f"https://archive.org/download/{self.item_name}/TDC_Release_14.zip/{encoded_full_path}"
+
+
+# Example of how to add a new version:
+#
+# class TotalDOSCollectionRelease15(ArchiveOrgCollection):
+#     """
+#     Specific implementation for Total DOS Collection Release 15.
+#     """
+#
+#     def __init__(self, source: str, cache_dir: str):
+#         super().__init__(source, cache_dir, "Total DOS Collection Release 15")
+#
+#     def _build_download_url(self, encoded_full_path: str) -> str:
+#         """
+#         Builds the download URL specific to TDC Release 15 structure.
+#         """
+#         return f"https://archive.org/download/{self.item_name}/TDC_Release_15.zip/{encoded_full_path}"
+#
+#     def _parse_filename(self, filename: str) -> Dict:
+#         """
+#         Override if Release 15 has different filename patterns.
+#         """
+#         # Custom parsing logic for Release 15 if needed
+#         return super()._parse_filename(filename)

dosctl/collections/base.py

@@ -0,0 +1,21 @@
+from abc import ABC, abstractmethod
+from typing import List, Dict
+
+class BaseCollection(ABC):
+    """
+    Abstract base class for a game collection.
+    """
+    def __init__(self, source: str):
+        self.source = source
+
+    @abstractmethod
+    def load(self) -> None:
+        pass
+
+    @abstractmethod
+    def get_games(self) -> List[Dict]:
+        pass
+
+    @abstractmethod
+    def download_game(self, game_name: str, destination: str) -> None:
+        pass

dosctl/collections/factory.py

@@ -0,0 +1,35 @@
+"""Collection factory for creating appropriate collection instances."""
+from .archive_org import TotalDOSCollectionRelease14
+
+# Registry of available collection implementations
+COLLECTION_REGISTRY = {
+    "tdc_release_14": TotalDOSCollectionRelease14,
+    # Future versions can be added here:
+    # "tdc_release_15": TotalDOSCollectionRelease15,
+}
+
+def create_collection(collection_type: str, source: str, cache_dir: str):
+    """
+    Factory function to create collection instances.
+    
+    Args:
+        collection_type: The type of collection (e.g., "tdc_release_14")
+        source: The source URL for the collection
+        cache_dir: Directory for caching collection data
+        
+    Returns:
+        An instance of the appropriate collection class
+        
+    Raises:
+        ValueError: If the collection_type is not supported
+    """
+    if collection_type not in COLLECTION_REGISTRY:
+        available = ", ".join(COLLECTION_REGISTRY.keys())
+        raise ValueError(f"Unknown collection type '{collection_type}'. Available: {available}")
+    
+    collection_class = COLLECTION_REGISTRY[collection_type]
+    return collection_class(source, cache_dir)
+
+def get_available_collections():
+    """Returns a list of available collection types."""
+    return list(COLLECTION_REGISTRY.keys())

dosctl/commands/delete.py

@@ -0,0 +1,42 @@
+import click
+import shutil
+from dosctl.config import INSTALLED_DIR, DOWNLOADS_DIR
+from dosctl.lib.decorators import ensure_cache
+
+@click.command()
+@click.argument('game_id')
+@ensure_cache
+def delete(collection, game_id):
+    """
+    Deletes an installed game.
+    """
+    game_install_path = INSTALLED_DIR / game_id
+
+    if not game_install_path.exists() or not game_install_path.is_dir():
+        click.echo(f"Error: Game with ID '{game_id}' is not installed.", err=True)
+        return
+
+    game = collection._find_game(game_id)
+    game_name = game['name'] if game else f"Game ID {game_id}"
+    downloaded_zip = DOWNLOADS_DIR / f"{game_name}.zip"
+
+    click.echo(f"You are about to delete the files for '{game_name}'.")
+    click.echo(f"Installation: {game_install_path}")
+    if downloaded_zip.exists():
+        click.echo(f"Downloaded Archive: {downloaded_zip}")
+
+    if not click.confirm("Are you sure you want to continue?"):
+        click.echo("Deletion cancelled.")
+        return
+
+    try:
+        if game_install_path.exists():
+            shutil.rmtree(game_install_path)
+            click.echo(f"✅ Successfully deleted installation directory.")
+
+        if downloaded_zip.exists():
+            downloaded_zip.unlink()
+            click.echo(f"✅ Successfully deleted downloaded archive.")
+
+    except Exception as e:
+        click.echo(f"An error occurred during deletion: {e}", err=True)

dosctl/commands/inspect.py

@@ -0,0 +1,47 @@
+import click
+from dosctl.config import INSTALLED_DIR
+from dosctl.lib.decorators import ensure_cache
+
+@click.command()
+@click.argument('game_id')
+@click.option('-e', '--executables', is_flag=True, help='Show only executable files (.exe, .com, .bat).')
+@ensure_cache
+def inspect(collection, game_id, executables):
+    """
+    Inspects the installed files for a given game.
+    """
+    game_install_path = INSTALLED_DIR / game_id
+
+    if not game_install_path.exists() or not game_install_path.is_dir():
+        click.echo(f"Error: Game with ID '{game_id}' is not installed.", err=True)
+        return
+
+    game = collection._find_game(game_id)
+    game_name = game['name'] if game else "Unknown Game"
+
+    click.echo(f"Inspecting files for '{game_name}' (ID: {game_id})")
+    click.echo(f"Location: {game_install_path}")
+    click.echo("-" * 40)
+
+    # Use rglob to list all files recursively
+    files = sorted([f for f in game_install_path.rglob('*') if f.is_file()])
+
+    if executables:
+        # Filter to only executable file extensions
+        executable_extensions = {'.exe', '.com', '.bat'}
+        files = [f for f in files if f.suffix.lower() in executable_extensions]
+
+    if not files:
+        if executables:
+            click.echo("No executable files found in the installation directory.")
+        else:
+            click.echo("No files found in the installation directory.")
+        return
+
+    if executables:
+        click.echo("Executable files:")
+
+    for file_path in files:
+        # Get the path relative to the game's install directory
+        relative_path = file_path.relative_to(game_install_path)
+        click.echo(f"  {relative_path}")

dosctl/commands/list.py

@@ -0,0 +1,25 @@
+import click
+from dosctl.lib.decorators import ensure_cache
+from dosctl.lib.display import sort_games, display_games
+from dosctl.config import INSTALLED_DIR
+
+@click.command(name="list")
+@click.option('-s', '--sort-by', type=click.Choice(['name', 'year'], case_sensitive=False), default='name', help='Sort the list by name or year.')
+@click.option('-i', '--installed', is_flag=True, default=False, help='Only list installed games.')
+@ensure_cache
+def list_games(collection, sort_by, installed):
+    """Lists all available games from the local cache."""
+    
+    games = collection.get_games()
+
+    if installed:
+        installed_ids = {p.name for p in INSTALLED_DIR.iterdir() if p.is_dir()}
+        games = [g for g in games if g['id'] in installed_ids]
+
+    if not games:
+        message = "No games are currently installed." if installed else "No games found in cache."
+        click.echo(message)
+        return
+
+    games = sort_games(games, sort_by)
+    display_games(games)

dosctl/commands/refresh.py

@@ -0,0 +1,25 @@
+import click
+from dosctl.collections.archive_org import TotalDOSCollectionRelease14
+from dosctl.config import DEFAULT_COLLECTION_SOURCE, COLLECTION_CACHE_DIR, ensure_dirs_exist
+
+@click.command()
+@click.option('--force', is_flag=True, default=False, help='Force a re-download of the game list.')
+def refresh(force):
+    """
+    Downloads the latest game list from the collection source.
+    """
+    if not force:
+        click.echo("This command will re-download the entire game list.")
+        click.echo("Use 'dosctl refresh --force' to confirm.")
+        return
+
+    click.echo("Ensuring application directories exist...")
+    ensure_dirs_exist()
+
+    collection = TotalDOSCollectionRelease14(
+        source=DEFAULT_COLLECTION_SOURCE,
+        cache_dir=COLLECTION_CACHE_DIR
+    )
+
+    click.echo("Forcing a refresh of the game lists...")
+    collection.ensure_cache_is_present(force_refresh=True)

dosctl/commands/run.py

@@ -0,0 +1,119 @@
+import click
+import subprocess
+import textwrap
+from dosctl.lib.decorators import ensure_cache
+from dosctl.lib.game import install_game
+from dosctl.lib.config_store import get_game_command, set_game_command
+from dosctl.lib.system import is_dosbox_installed
+from dosctl.lib.executables import find_executables, executable_exists
+
+@click.command()
+@click.argument('game_id')
+@click.argument('command_parts', nargs=-1)
+@click.option('-c', '--configure', is_flag=True, default=False, help='Force re-selection of the default executable.')
+@ensure_cache
+def run(collection, game_id, command_parts, configure):
+    """
+    Runs a game. Prompts for an executable on the first run or when --configure is used.
+    """
+    if not is_dosbox_installed():
+        help_text = textwrap.dedent("""
+            Error: 'dosbox' command not found in your PATH.
+
+            Please install DOSBox. We recommend DOSBox Staging for the best experience.
+
+            To install with Homebrew on macOS:
+              brew install dosbox           # For standard DOSBox
+              brew install dosbox-staging # For DOSBox Staging (recommended)
+
+            If you install DOSBox Staging, you may need to create a symlink so `dosctl` can find it:
+              ln -s "$(brew --prefix dosbox-staging)/bin/dosbox-staging" ~/.local/bin/dosbox
+        """)
+        click.echo(help_text, err=True)
+        return
+
+    try:
+        _, game_install_path = install_game(collection, game_id)
+        if not game_install_path:
+            return
+
+        # Determine the command to run
+        chosen_command_str = _get_or_prompt_command(game_id, game_install_path, command_parts, configure)
+        if not chosen_command_str:
+            return
+
+        # Save the chosen command for future runs
+        set_game_command(game_id, chosen_command_str)
+
+        # Validate that the chosen executable exists
+        executable_name = chosen_command_str.split()[0]
+        if not executable_exists(game_install_path, executable_name):
+            click.echo(f"Error: Executable '{executable_name}' not found.", err=True)
+            set_game_command(game_id, None)
+            return
+
+        # Launch the game
+        _launch_game(game_install_path, chosen_command_str)
+
+    except FileNotFoundError as e:
+        click.echo(f"Error: {e}", err=True)
+    except Exception as e:
+        click.echo(f"An unexpected error occurred: {e}", err=True)
+
+def _get_or_prompt_command(game_id, game_install_path, command_parts, configure):
+    """Get the command to run, prompting if necessary."""
+    if configure:
+        return _prompt_for_executable(game_install_path, configure)
+
+    # If user provides command on CLI, use it
+    if command_parts:
+        return " ".join(command_parts)
+
+    # Check for saved command
+    saved_command = get_game_command(game_id)
+    if saved_command:
+        return saved_command
+
+    # First run - prompt for executable
+    click.echo(f"No default executable set for game '{game_id}'. Searching...")
+    return _prompt_for_executable(game_install_path, configure)
+
+def _prompt_for_executable(game_install_path, force_menu=False):
+    """Prompt user to select an executable."""
+    executables = find_executables(game_install_path)
+
+    if not executables:
+        click.echo(f"Error: No executables (.exe, .com, .bat) found in the archive.", err=True)
+        return None
+
+    # If there's only one option and we're not forcing the menu, choose it automatically
+    if len(executables) == 1 and not force_menu:
+        click.echo(f"Found a single executable: '{executables[0]}'. Setting as default.")
+        return executables[0]
+
+    # Show menu for user selection
+    while True:
+        menu_items = [f"  {i}: {exe_name.upper()}" for i, exe_name in enumerate(executables, 1)]
+        click.echo("Please choose one of the following to run:")
+        click.echo("\n".join(menu_items))
+
+        choice = click.prompt("Select a file to execute", type=int)
+        if 1 <= choice <= len(executables):
+            return executables[choice - 1]
+        else:
+            click.echo("Invalid choice. Please try again.", err=True)
+
+def _launch_game(game_install_path, chosen_command_str):
+    """Launch the game with DOSBox."""
+    click.echo(f"Starting '{chosen_command_str.upper()}' with DOSBox...")
+
+    command = [
+        'dosbox',
+        '-c', f'MOUNT C "{game_install_path}"',
+        '-c', 'C:',
+        '-c', chosen_command_str
+    ]
+
+    subprocess.Popen(command,
+                     stdout=subprocess.DEVNULL,
+                     stderr=subprocess.DEVNULL)

dosctl/commands/search.py

@@ -0,0 +1,47 @@
+import click
+import re
+from dosctl.lib.decorators import ensure_cache
+from dosctl.lib.display import sort_games, display_games
+
+@click.command()
+@click.argument('query', required=False)
+@click.option('-c', '--case-sensitive', is_flag=True, default=False, help='Perform a case-sensitive search.')
+@click.option('-y', '--year', type=int, help='Filter search results by a specific year.')
+@click.option('-s', '--sort-by', type=click.Choice(['name', 'year'], case_sensitive=False), default='name', help='Sort the results by name or year.')
+@ensure_cache
+def search(collection, query, case_sensitive, year, sort_by):
+    """
+    Searches for games in the local cache.
+    """
+    if not query and not year:
+        click.echo("Error: You must provide a search query or a year.", err=True)
+        return
+
+    games = collection.get_games()
+
+    if not games:
+        click.echo("No games found in cache.")
+        return
+
+    # Search Logic
+    results = []
+    flags = 0 if case_sensitive else re.IGNORECASE
+
+    for game in games:
+        # Year filter
+        if year and str(game.get('year')) != str(year):
+            continue
+
+        # Name filter (only if query is provided)
+        if query and not re.search(query, game['name'], flags):
+            continue
+
+        results.append(game)
+
+    # Display Logic
+    if not results:
+        click.echo("No games found matching your criteria.")
+        return
+
+    results = sort_games(results, sort_by)
+    display_games(results, f"Found {len(results)} game(s):")

dosctl/config.py

@@ -0,0 +1,23 @@
+from pathlib import Path
+
+# Define the base directories for config and data
+CONFIG_DIR = Path.home() / ".config" / "dosctl"
+DATA_DIR = Path.home() / ".local" / "share" / "dosctl"
+
+# Define the specific cache directory for collections
+COLLECTION_CACHE_DIR = DATA_DIR / "collections"
+
+# Define game-specific directories
+DOWNLOADS_DIR = DATA_DIR / "downloads"
+INSTALLED_DIR = DATA_DIR / "installed"
+
+# Define the default source URL for the main game collection
+DEFAULT_COLLECTION_SOURCE = "https://ia800906.us.archive.org/view_archive.php?archive=/4/items/Total_DOS_Collection_Release_14/TDC_Release_14.zip"
+
+def ensure_dirs_exist():
+    """Create the config and data directories if they don't exist."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    COLLECTION_CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    DOWNLOADS_DIR.mkdir(parents=True, exist_ok=True)
+    INSTALLED_DIR.mkdir(parents=True, exist_ok=True)

dosctl/lib/config_store.py

@@ -0,0 +1,44 @@
+import json
+from pathlib import Path
+from dosctl.config import CONFIG_DIR
+
+CONFIG_FILE = CONFIG_DIR / "run_config.json"
+
+def load_run_config() -> dict:
+    """Loads the executable configuration file."""
+    if not CONFIG_FILE.exists():
+        return {}
+    try:
+        with open(CONFIG_FILE, "r") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError):
+        # If the file is corrupted or unreadable, treat it as empty
+        return {}
+
+def save_run_config(config: dict) -> None:
+    """Saves the executable configuration file."""
+    # Ensure the config directory exists
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+    try:
+        with open(CONFIG_FILE, "w") as f:
+            json.dump(config, f, indent=2)
+    except OSError as e:
+        # Handle write errors gracefully
+        print(f"Warning: Could not save configuration: {e}")
+
+def get_game_command(game_id: str) -> str | None:
+    """Gets the saved command for a specific game."""
+    config = load_run_config()
+    return config.get(game_id)
+
+def set_game_command(game_id: str, command: str | None) -> None:
+    """Saves the chosen command for a specific game. If command is None, removes the entry."""
+    config = load_run_config()
+
+    if command is None:
+        config.pop(game_id, None)  # Remove entry if exists
+    else:
+        config[game_id] = command
+
+    save_run_config(config)