reznum-minesweeper 0.2.2__py3-none-any.whl

minesweeper_cli/__init__.py

@@ -0,0 +1,5 @@
+"""Minesweeper CLI - A modern, colorful terminal Minesweeper game."""
+
+__version__ = "0.2.2"
+__author__ = "Made with ❤️ by ItsReZNuM"
+__all__ = ["__version__", "__author__"]

minesweeper_cli/__main__.py

@@ -0,0 +1,7 @@
+"""Main entrypoint when invoked as a module: python -m minesweeper_cli."""
+
+import sys
+from minesweeper_cli.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

minesweeper_cli/board.py

@@ -0,0 +1,225 @@
+"""Minesweeper board engine and gameplay mechanics."""
+
+import random
+from enum import Enum, auto
+from typing import List, Tuple, Set, Optional
+from minesweeper_cli.cell import Cell
+
+
+class GameStatus(Enum):
+    """Lifecycle states of a Minesweeper game."""
+    READY = auto()      # Board created, first move not yet taken
+    PLAYING = auto()    # Game active, timer ticking
+    WON = auto()        # All non-mine cells revealed
+    LOST = auto()       # Mine triggered
+
+
+class Board:
+    """Core Minesweeper game board."""
+
+    def __init__(self, width: int, height: int, num_mines: int) -> None:
+        if width < 1 or height < 1:
+            raise ValueError("Board dimensions must be at least 1x1")
+        total_cells = width * height
+        if num_mines < 0 or num_mines >= total_cells:
+            raise ValueError(f"Mines ({num_mines}) must be between 0 and {total_cells - 1}")
+
+        self.width = width
+        self.height = height
+        self.num_mines = num_mines
+        self.grid: List[List[Cell]] = [[Cell() for _ in range(width)] for _ in range(height)]
+        self.status = GameStatus.READY
+        self.first_move = True
+        self.revealed_count = 0
+        self.flagged_count = 0
+        self.exploded_pos: Optional[Tuple[int, int]] = None
+
+    def in_bounds(self, x: int, y: int) -> bool:
+        """Check if grid coordinates (x=column, y=row) are within board bounds."""
+        return 0 <= x < self.width and 0 <= y < self.height
+
+    def get_cell(self, x: int, y: int) -> Cell:
+        """Get cell at coordinates (x, y)."""
+        if not self.in_bounds(x, y):
+            raise IndexError(f"Coordinates ({x}, {y}) out of bounds")
+        return self.grid[y][x]
+
+    def get_neighbors(self, x: int, y: int) -> List[Tuple[int, int]]:
+        """Return list of (nx, ny) coordinates for all valid adjacent neighbors."""
+        neighbors = []
+        for dy in (-1, 0, 1):
+            for dx in (-1, 0, 1):
+                if dx == 0 and dy == 0:
+                    continue
+                nx, ny = x + dx, y + dy
+                if self.in_bounds(nx, ny):
+                    neighbors.append((nx, ny))
+        return neighbors
+
+    def place_mines(self, safe_x: int, safe_y: int) -> None:
+        """Generate mines with first-move protection ensuring safe_x, safe_y is safe."""
+        # Prefer guaranteeing safe_x, safe_y and its 8 neighbors have no mines if space permits
+        forbidden: Set[Tuple[int, int]] = {(safe_x, safe_y)}
+        neighbors = self.get_neighbors(safe_x, safe_y)
+        total_cells = self.width * self.height
+
+        if total_cells - (len(neighbors) + 1) >= self.num_mines:
+            forbidden.update(neighbors)
+
+        candidates = [
+            (x, y)
+            for y in range(self.height)
+            for x in range(self.width)
+            if (x, y) not in forbidden
+        ]
+
+        # If candidates are fewer than required mines (dense custom board), fall back to only safe cell
+        if len(candidates) < self.num_mines:
+            candidates = [
+                (x, y)
+                for y in range(self.height)
+                for x in range(self.width)
+                if (x, y) != (safe_x, safe_y)
+            ]
+
+        mine_coords = set(random.sample(candidates, self.num_mines))
+
+        for x, y in mine_coords:
+            self.grid[y][x].is_mine = True
+
+        # Calculate neighbor mine counts for each cell
+        for y in range(self.height):
+            for x in range(self.width):
+                if self.grid[y][x].is_mine:
+                    continue
+                count = sum(1 for nx, ny in self.get_neighbors(x, y) if self.grid[ny][nx].is_mine)
+                self.grid[y][x].adjacent_mines = count
+
+    def reveal(self, x: int, y: int) -> bool:
+        """Reveal cell at (x, y). Returns True if action succeeded."""
+        if not self.in_bounds(x, y) or self.status in (GameStatus.WON, GameStatus.LOST):
+            return False
+
+        cell = self.grid[y][x]
+        if not cell.can_reveal:
+            return False
+
+        # First move protection: generate mine layout ensuring first reveal is safe
+        if self.first_move:
+            self.place_mines(x, y)
+            self.first_move = False
+            self.status = GameStatus.PLAYING
+
+        if cell.is_mine:
+            cell.is_exploded = True
+            self.exploded_pos = (x, y)
+            self.status = GameStatus.LOST
+            self._reveal_all_mines()
+            return True
+
+        # Flood fill reveal
+        self._flood_reveal(x, y)
+        self._check_win_condition()
+        return True
+
+    def _flood_reveal(self, start_x: int, start_y: int) -> None:
+        """Breadth-first search expanding zero-neighbor cells and boundary numbers."""
+        queue: List[Tuple[int, int]] = [(start_x, start_y)]
+        visited: Set[Tuple[int, int]] = set()
+
+        while queue:
+            cx, cy = queue.pop(0)
+            if (cx, cy) in visited:
+                continue
+            visited.add((cx, cy))
+
+            cell = self.grid[cy][cx]
+            if cell.is_mine:
+                continue
+
+            if not cell.is_revealed and not cell.is_flagged:
+                cell.is_revealed = True
+                self.revealed_count += 1
+
+                if cell.adjacent_mines == 0:
+                    for nx, ny in self.get_neighbors(cx, cy):
+                        if (nx, ny) not in visited:
+                            neighbor_cell = self.grid[ny][nx]
+                            if not neighbor_cell.is_revealed and not neighbor_cell.is_flagged and not neighbor_cell.is_mine:
+                                queue.append((nx, ny))
+
+    def chord_reveal(self, x: int, y: int) -> bool:
+        """Reveal surrounding unflagged cells if flagged neighbor count matches cell number."""
+        if not self.in_bounds(x, y) or self.status != GameStatus.PLAYING:
+            return False
+
+        cell = self.grid[y][x]
+        if not cell.is_revealed or cell.adjacent_mines == 0:
+            return False
+
+        neighbors = self.get_neighbors(x, y)
+        flagged_neighbors = sum(1 for nx, ny in neighbors if self.grid[ny][nx].is_flagged)
+
+        if flagged_neighbors != cell.adjacent_mines:
+            return False
+
+        any_revealed = False
+        for nx, ny in neighbors:
+            n_cell = self.grid[ny][nx]
+            if not n_cell.is_revealed and not n_cell.is_flagged:
+                if n_cell.is_mine:
+                    n_cell.is_exploded = True
+                    self.exploded_pos = (nx, ny)
+                    self.status = GameStatus.LOST
+                    self._reveal_all_mines()
+                    return True
+                self._flood_reveal(nx, ny)
+                any_revealed = True
+
+        self._check_win_condition()
+        return any_revealed
+
+    def toggle_flag(self, x: int, y: int) -> bool:
+        """Toggle flag marker on hidden cell (x, y)."""
+        if not self.in_bounds(x, y) or self.status in (GameStatus.WON, GameStatus.LOST):
+            return False
+
+        cell = self.grid[y][x]
+        if cell.is_revealed:
+            return False
+
+        if cell.is_flagged:
+            cell.is_flagged = False
+            self.flagged_count -= 1
+        else:
+            cell.is_flagged = True
+            self.flagged_count += 1
+
+        return True
+
+    def _check_win_condition(self) -> None:
+        """Check if all non-mine cells have been opened."""
+        total_cells = self.width * self.height
+        non_mine_cells = total_cells - self.num_mines
+        if self.revealed_count == non_mine_cells and self.status != GameStatus.LOST:
+            self.status = GameStatus.WON
+            # Auto-flag remaining hidden mines for polished display
+            for y in range(self.height):
+                for x in range(self.width):
+                    c = self.grid[y][x]
+                    if c.is_mine and not c.is_flagged:
+                        c.is_flagged = True
+                        self.flagged_count += 1
+
+    def _reveal_all_mines(self) -> None:
+        """Expose mine positions on game loss."""
+        for y in range(self.height):
+            for x in range(self.width):
+                c = self.grid[y][x]
+                if c.is_mine:
+                    c.is_revealed = True
+
+    @property
+    def remaining_flags(self) -> int:
+        """Count of flags remaining relative to total mines."""
+        return self.num_mines - self.flagged_count

minesweeper_cli/cell.py

@@ -0,0 +1,30 @@
+"""Minesweeper individual cell representation."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Cell:
+    """Represents a single tile on the Minesweeper board."""
+    is_mine: bool = False
+    is_revealed: bool = False
+    is_flagged: bool = False
+    is_exploded: bool = False
+    adjacent_mines: int = 0
+
+    @property
+    def is_hidden(self) -> bool:
+        """Return True if the cell has not yet been opened."""
+        return not self.is_revealed
+
+    @property
+    def can_reveal(self) -> bool:
+        """A cell can only be revealed if it is hidden and not flagged."""
+        return not self.is_revealed and not self.is_flagged
+
+    def toggle_flag(self) -> bool:
+        """Toggle flag status if hidden. Returns True if now flagged, False otherwise."""
+        if self.is_revealed:
+            return False
+        self.is_flagged = not self.is_flagged
+        return self.is_flagged

minesweeper_cli/cli.py

@@ -0,0 +1,84 @@
+"""Command-line interface entrypoint and argument parser."""
+
+import argparse
+import sys
+from typing import List, Optional
+
+from minesweeper_cli import __version__
+from minesweeper_cli.config import APP_NAME, DIFFICULTIES
+from minesweeper_cli.menu import MenuController
+from minesweeper_cli.records import RecordsManager
+from minesweeper_cli.settings import SettingsManager
+from minesweeper_cli.themes import THEMES
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Build command-line arguments parser."""
+    parser = argparse.ArgumentParser(
+        prog="minesweeper",
+        description=f"{APP_NAME} - A modern, colorful terminal Minesweeper game written in Python.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    parser.add_argument(
+        "-v", "--version",
+        action="version",
+        version=f"{APP_NAME} {__version__}",
+        help="Show version information and exit.",
+    )
+
+    parser.add_argument(
+        "-d", "--difficulty",
+        choices=["easy", "medium", "hard", "expert"],
+        type=str.lower,
+        help="Directly launch game with specified difficulty preset.",
+    )
+
+    parser.add_argument(
+        "-c", "--custom",
+        action="store_true",
+        help="Directly open custom board setup dialog.",
+    )
+
+    parser.add_argument(
+        "-t", "--theme",
+        choices=list(THEMES.keys()),
+        type=str.lower,
+        help="Select visual color theme (classic, matrix, ocean, dracula, cyberpunk, nord, monochrome).",
+    )
+
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """CLI execution entrypoint."""
+    parser = create_parser()
+    args = parser.parse_args(argv)
+
+    settings_mgr = SettingsManager()
+    records_mgr = RecordsManager()
+
+    if args.theme:
+        settings_mgr.settings.theme = args.theme
+        settings_mgr.save()
+
+    menu = MenuController(settings_manager=settings_mgr, records_manager=records_mgr)
+
+    try:
+        if args.difficulty:
+            chosen = DIFFICULTIES[args.difficulty]
+            menu.launch_game(chosen.width, chosen.height, chosen.mines, chosen.name)
+            return 0
+        elif args.custom:
+            menu.menu_custom_game()
+            return 0
+        else:
+            menu.run()
+            return 0
+    except KeyboardInterrupt:
+        sys.stdout.write("\nThanks for playing Minesweeper CLI!\n")
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

minesweeper_cli/config.py

@@ -0,0 +1,62 @@
+"""Global configuration, difficulty presets, and branding metadata."""
+
+from dataclasses import dataclass
+from typing import Dict
+
+APP_NAME = "Minesweeper CLI"
+APP_SLUG = "minesweeper-cli"
+AUTHOR = "Made with ❤️ by ItsReZNuM"
+GITHUB_PROFILE = "https://github.com/ItsReZNuM"
+GITHUB_REPO = "https://github.com/ItsReZNuM/Minesweeper-CLI"
+TELEGRAM = "https://t.me/ItsReZNuM"
+INSTAGRAM = "https://instagram.com/rez.num"
+TERMINAL_DEFAULT = "Classic CMD"
+
+
+@dataclass(frozen=True)
+class DifficultyConfig:
+    """Predefined difficulty configuration."""
+    name: str
+    width: int
+    height: int
+    mines: int
+    description: str
+
+
+DIFFICULTIES: Dict[str, DifficultyConfig] = {
+    "easy": DifficultyConfig(
+        name="Easy",
+        width=9,
+        height=9,
+        mines=10,
+        description="9x9 board with 10 mines (Beginner friendly)",
+    ),
+    "medium": DifficultyConfig(
+        name="Medium",
+        width=16,
+        height=16,
+        mines=40,
+        description="16x16 board with 40 mines (Standard challenge)",
+    ),
+    "hard": DifficultyConfig(
+        name="Hard",
+        width=30,
+        height=16,
+        mines=99,
+        description="30x16 board with 99 mines (Classic advanced)",
+    ),
+    "expert": DifficultyConfig(
+        name="Expert",
+        width=30,
+        height=24,
+        mines=150,
+        description="30x24 board with 150 mines (Master challenge)",
+    ),
+}
+
+# Custom mode boundary constraints
+MIN_BOARD_WIDTH = 4
+MAX_BOARD_WIDTH = 60
+MIN_BOARD_HEIGHT = 4
+MAX_BOARD_HEIGHT = 40
+MIN_MINES_COUNT = 1

minesweeper_cli/controls.py

@@ -0,0 +1,97 @@
+"""Game controls, key mapping definitions, and conflict validation."""
+
+from typing import Dict, List, Optional, Tuple
+
+ACTION_UP = "up"
+ACTION_DOWN = "down"
+ACTION_LEFT = "left"
+ACTION_RIGHT = "right"
+ACTION_REVEAL = "reveal"
+ACTION_FLAG = "flag"
+ACTION_CHORD = "chord"
+ACTION_RESTART = "restart"
+ACTION_QUIT = "quit"
+
+ALL_ACTIONS = [
+    ACTION_UP,
+    ACTION_DOWN,
+    ACTION_LEFT,
+    ACTION_RIGHT,
+    ACTION_REVEAL,
+    ACTION_FLAG,
+    ACTION_CHORD,
+    ACTION_RESTART,
+    ACTION_QUIT,
+]
+
+ACTION_LABELS = {
+    ACTION_UP: "Move Up",
+    ACTION_DOWN: "Move Down",
+    ACTION_LEFT: "Move Left",
+    ACTION_RIGHT: "Move Right",
+    ACTION_REVEAL: "Reveal Cell",
+    ACTION_FLAG: "Place / Remove Flag",
+    ACTION_CHORD: "Chord Reveal (Quick Open)",
+    ACTION_RESTART: "Restart Game",
+    ACTION_QUIT: "Quit to Menu",
+}
+
+DEFAULT_KEY_BINDINGS: Dict[str, List[str]] = {
+    ACTION_UP: ["w", "up"],
+    ACTION_DOWN: ["s", "down"],
+    ACTION_LEFT: ["a", "left"],
+    ACTION_RIGHT: ["d", "right"],
+    ACTION_REVEAL: ["enter", "space"],
+    ACTION_FLAG: ["f"],
+    ACTION_CHORD: ["c"],
+    ACTION_RESTART: ["r"],
+    ACTION_QUIT: ["q", "escape"],
+}
+
+
+def normalize_key(key: str) -> str:
+    """Normalize key string representation for comparison."""
+    if not key:
+        return ""
+    mapping = {
+        "\r": "enter",
+        "\n": "enter",
+        " ": "space",
+        "\x1b": "escape",
+        "esc": "escape",
+    }
+    if key in mapping:
+        return mapping[key]
+    cleaned = key.strip().lower()
+    return mapping.get(cleaned, cleaned)
+
+
+def validate_key_bindings(bindings: Dict[str, List[str]]) -> Tuple[bool, Optional[str]]:
+    """Verify that every action has at least one key and no key is assigned to multiple actions."""
+    for action in ALL_ACTIONS:
+        if action not in bindings or not bindings[action]:
+            return False, f"Action '{ACTION_LABELS.get(action, action)}' must have at least one key assigned."
+
+    seen_keys: Dict[str, str] = {}
+    for action, keys in bindings.items():
+        for k in keys:
+            norm = normalize_key(k)
+            if not norm:
+                continue
+            if norm in seen_keys and seen_keys[norm] != action:
+                existing_action = ACTION_LABELS.get(seen_keys[norm], seen_keys[norm])
+                new_action = ACTION_LABELS.get(action, action)
+                return False, f"Key '{norm}' conflicts between '{existing_action}' and '{new_action}'."
+            seen_keys[norm] = action
+
+    return True, None
+
+
+def get_action_for_key(key: str, bindings: Dict[str, List[str]]) -> Optional[str]:
+    """Resolve normalized key string into an action name."""
+    normalized = normalize_key(key)
+    for action, keys in bindings.items():
+        for k in keys:
+            if normalize_key(k) == normalized:
+                return action
+    return None