machineconfig 6.23__py3-none-any.whl → 8.12__py3-none-any.whl

machineconfig/scripts/python/{repos_helpers/count_lines.py → helpers_repos/repo_analyzer_2.py}

@@ -1,189 +1,12 @@
-
-from typing import TYPE_CHECKING, Annotated
 from git import Repo
-from collections import defaultdict
+from machineconfig.scripts.python.helpers_repos.repo_analyzer_1 import count_python_lines, get_default_branch
 from datetime import datetime
-
+import polars as pl
 from pathlib import Path
-from rich.progress import track
-import typer
-
-
-if TYPE_CHECKING:
-    from typing import Any, Dict, List, Optional, Union
-    import polars as pl
-
-
-app = typer.Typer()
-
-
-def count_lines_in_commit(commit: "Any") -> int:
-    _total_lines = 0
-    for _file in commit.stats.files:
-        if str(_file).endswith(".py"):
-            _blob = commit.tree / _file
-            _total_lines += len(_blob.data_stream.read().decode("utf-8").splitlines())
-    return _total_lines
-
-
-def count_historical_loc(repo_path: str) -> int:
-    repo = Repo(repo_path)
-    file_line_counts: "Dict[str, int]" = defaultdict(int)
-    total_commits: int = sum(1 for _ in repo.iter_commits())
-    print(f"Total commits to process: {total_commits}")
-    for i, commit in enumerate(repo.iter_commits(), 1):
-        if i % 100 == 0 or i == total_commits:
-            print(f"Processing commit {i}/{total_commits} ({i / total_commits:.1%})")
-        try:
-            # Handle initial commits that have no parents
-            if not commit.parents:
-                # For initial commit, count all lines in Python files
-                for file in commit.stats.files:
-                    if str(file).endswith(".py"):
-                        file_line_counts[str(file)] += commit.stats.files[file]["insertions"]
-            else:
-                # For commits with parents, use stats
-                for file in commit.stats.files:
-                    if str(file).endswith(".py"):
-                        file_line_counts[str(file)] += commit.stats.files[file]["insertions"]
-        except Exception:
-            # If stats fail (e.g., corrupted parent), skip this commit
-            print(f"Warning: Could not get stats for commit {commit.hexsha[:8]}, skipping")
-            continue
-
-    print(f"\nProcessed files: {len(file_line_counts)}")
-    return sum(file_line_counts.values())
-
-def count_python_lines(commit: "Any") -> int:
-    """Count total lines in Python files for a specific commit"""
-    total_lines = 0
-    try:
-        for blob in commit.tree.traverse():
-            if blob.path.endswith(".py"):
-                try:
-                    content = blob.data_stream.read().decode("utf-8")
-                    total_lines += len(content.splitlines())
-                except Exception as _e:
-                    continue
-    except Exception as _e:
-        return 0
-    return total_lines
-def get_default_branch(repo: Repo) -> str:
-    """Get the default branch name of the repository"""
-    try:
-        _ = repo.refs["main"]
-        return "main"  # First try 'main'
-    except IndexError:
-        try:
-            _ = repo.refs["master"]
-            return "master"  # Then try 'master'
-        except IndexError:
-            return repo.head.reference.name  # If neither exists, get the branch the HEAD is pointing to
-
-
-@app.command()
-def count_historical(repo_path: Annotated[str, typer.Argument(..., help="Path to the git repository")]):
-    """Count total historical lines of Python code in the repository."""
-    print(f"Analyzing repository: {repo_path}")
-    total_loc: int = count_historical_loc(repo_path)
-    print(f"\nTotal historical lines of Python code: {total_loc}")
-
-
-@app.command()
-def analyze_over_time(repo_path: Annotated[str, typer.Argument(..., help="Path to the git repository")]):
-    """Analyze a git repository to track Python code size over time with visualization."""
-    repo: Repo = Repo(repo_path)
-    branch_name: str = get_default_branch(repo)
-    print(f"🔍 Using branch: {branch_name}")
-    commit_data: "List[Dict[str, Any]]" = []
-    print("⏳ Analyzing commits...")
-    try:
-        commits = list(repo.iter_commits(branch_name))
-        from datetime import timezone
-
-        for commit in track(commits, description="Processing commits..."):
-            commit_data.append({"hash": commit.hexsha, "dtmExit": datetime.fromtimestamp(commit.committed_date, tz=timezone.utc), "lines": count_python_lines(commit)})
-    except Exception as e:
-        print(f"❌ Error analyzing commits: {str(e)}")
-        return
-
-    import polars as pl
-    import plotly.graph_objects as go
-
-    df = pl.DataFrame(commit_data)
-    df = df.sort("dtmExit")
-    # Create interactive plotly figure with dark theme and all bells and whistles
-    fig = go.Figure()
-    # Add line chart with gradient fill and sparkle effect
-    fig.add_trace(go.Scatter(x=df["dtmExit"], y=df["lines"], mode="lines", line={"width": 3, "color": "#00b4ff"}, fill="tozeroy", fillcolor="rgba(0, 180, 255, 0.2)", name="Lines of Code", hovertemplate="<b>Date:</b> %{x}<br><b>Lines:</b> %{y:,}<extra></extra>"))
-    # Add markers for significant points (min, max, last)
-    min_idx = df["lines"].arg_min()
-    max_idx = df["lines"].arg_max()
-    min_point = df.slice(min_idx, 1).to_dicts()[0] if min_idx is not None else {}
-    max_point = df.slice(max_idx, 1).to_dicts()[0] if max_idx is not None else {}
-    last_point = df.slice(-1, 1).to_dicts()[0]
-
-    # Add markers for significant points
-    fig.add_trace(
-        go.Scatter(
-            x=[min_point["dtmExit"], max_point["dtmExit"], last_point["dtmExit"]],
-            y=[min_point["lines"], max_point["lines"], last_point["lines"]],
-            mode="markers",
-            marker={"size": [10, 14, 12], "color": ["#ff4f4f", "#4fff4f", "#4f4fff"], "line": {"width": 2, "color": "white"}, "symbol": ["circle", "star", "diamond"]},
-            name="Key Points",
-            hovertemplate="<b>%{text}</b><br>Date: %{x}<br>Lines: %{y:,}<extra></extra>",
-            text=[f"🔽 Min: {min_point['lines']:,} lines", f"🔼 Max: {max_point['lines']:,} lines", f"📊 Current: {last_point['lines']:,} lines"],
-        )
-    )
-
-    # Add annotation only for current point
-    # annotations = [
-    #     {"x": last_point['date'], "y": last_point['lines'], "text": f"📊 Current: {last_point['lines']:,} lines", "showarrow": True, "arrowhead": 2, "arrowsize": 1,
-    #         "arrowwidth": 2, "arrowcolor": "#ffffff", "font": {"size": 14, "color": "#ffffff"}, "bgcolor": "#00b4ff", "bordercolor": "#ffffff",
-    #         "borderwidth": 1, "borderpad": 4, "ax": 40, "ay": -40}
-    # ]
-
-    # Update layout with dark theme and customizations
-    fig.update_layout(
-        title={"text": "✨ Python Code Base Size Over Time ✨", "y": 0.95, "x": 0.5, "xanchor": "center", "yanchor": "top", "font": {"size": 24, "color": "white"}},
-        xaxis_title="Date 📅",
-        yaxis_title="Lines of Code 📝",
-        hovermode="closest",
-        template="plotly_dark",
-        plot_bgcolor="rgba(25, 25, 35, 1)",
-        paper_bgcolor="rgba(15, 15, 25, 1)",
-        font={"family": "Arial, sans-serif", "size": 14, "color": "white"},  # annotations=annotations,
-        autosize=True,
-        height=700,
-        margin={"l": 80, "r": 80, "t": 100, "b": 80},
-        xaxis={"showgrid": True, "gridcolor": "rgba(80, 80, 100, 0.2)", "showline": True, "linecolor": "rgba(200, 200, 255, 0.2)", "tickfont": {"size": 12}},
-        yaxis={"showgrid": True, "gridcolor": "rgba(80, 80, 100, 0.2)", "showline": True, "linecolor": "rgba(200, 200, 255, 0.2)", "tickformat": ",", "tickfont": {"size": 12}},
-    )
-
-    # Add range slider for date selection
-    fig.update_xaxes(rangeslider_visible=True, rangeslider_thickness=0.05)
-
-    # Save as interactive HTML and static image
-    plot_dir = Path.home().joinpath("tmp_results", "tmp_images", Path(repo_path).name)
-    plot_dir.mkdir(parents=True, exist_ok=True)
-
-    html_path = plot_dir.joinpath("code_size_evolution.html")
-    png_path = plot_dir.joinpath("code_size_evolution.png")
-
-    fig.write_html(html_path, include_plotlyjs="cdn")
-    fig.write_image(png_path, width=1200, height=700, scale=2)
-
-    print(f"🖼️ Interactive plot saved as {html_path}")
-    print(f"🖼️ Static image saved as {png_path}")
-    # Print statistics
-    print("\n📊 Repository Statistics:")
-    print(f"📚 Total commits analyzed: {len(df)}")
-    print(f"🔙 Initial line count: {df['lines'][-1]:,}")
-    print(f"🔜 Final line count: {df['lines'][0]:,}")
-    print(f"📈 Net change: {df['lines'][0] - df['lines'][-1]:,} lines")
+from typing import Any, Dict, List, Union, Optional
 
 
-def _print_python_files_by_size_impl(repo_path: str) -> "Union[pl.DataFrame, Exception]":
+def print_python_files_by_size_impl(repo_path: str) -> "Union[pl.DataFrame, Exception]":
     import polars as pl
     import plotly.graph_objects as go
     import plotly.express as px
@@ -227,13 +50,25 @@ def _print_python_files_by_size_impl(repo_path: str) -> "Union[pl.DataFrame, Exc
         df = df.sort("lines", descending=True)
         df = df.filter(pl.col("lines") > 0)  # Filter out empty files
 
+        from rich.console import Console
+        from rich.table import Table
+
         # Add total count
         total_lines = int(df["lines"].sum())
         file_count: int = len(df)
-
+        console = Console()
         # Print the DataFrame
-        print("\n📊 Python Files Line Count (sorted max to min):")
-        print(df)
+        console.print("\n📊 Python Files Line Count (sorted max to min):")
+
+        table = Table(show_header=True, header_style="bold cyan")
+        table.add_column("#", justify="right")
+        table.add_column("File", overflow="fold")
+        table.add_column("Lines", justify="right")
+
+        for idx, row in enumerate(df.iter_rows(named=True), 1):
+            table.add_row(str(idx), row["filename"], f"{row['lines']:,}")
+
+        console.print(table)
         print(f"\n📁 Total Python files: {file_count}")
         print(f"📝 Total lines of Python code: {total_lines:,}")
 
@@ -335,14 +170,100 @@ def _print_python_files_by_size_impl(repo_path: str) -> "Union[pl.DataFrame, Exc
         return Exception(f"❌ Error analyzing repository: {str(e)}")
 
 
-@app.command()
-def print_python_files_by_size(repo_path: Annotated[str, typer.Argument(..., help="Path to the git repository")]):
-    """Print Python files sorted by size with visualizations."""
-    result = _print_python_files_by_size_impl(repo_path)
-    if isinstance(result, Exception):
-        print(f"Error: {result}")
+def analyze_over_time(repo_path: str):
+    """Analyze a git repository to track Python code size over time with visualization."""
+    repo: Repo = Repo(repo_path)
+    branch_name: str = get_default_branch(repo)
+    print(f"🔍 Using branch: {branch_name}")
+    commit_data: "List[Dict[str, Any]]" = []
+    print("⏳ Analyzing commits...")
+    try:
+        commits = list(repo.iter_commits(branch_name))
+        from datetime import timezone
+        from rich.progress import track
+        for commit in track(commits, description="Processing commits..."):
+            commit_data.append({"hash": commit.hexsha, "dtmExit": datetime.fromtimestamp(commit.committed_date, tz=timezone.utc), "lines": count_python_lines(commit)})
+    except Exception as e:
+        print(f"❌ Error analyzing commits: {str(e)}")
         return
 
+    import polars as pl
+    import plotly.graph_objects as go
+
+    df = pl.DataFrame(commit_data)
+    df = df.sort("dtmExit")
+    # Create interactive plotly figure with dark theme and all bells and whistles
+    fig = go.Figure()
+    # Add line chart with gradient fill and sparkle effect
+    fig.add_trace(go.Scatter(x=df["dtmExit"], y=df["lines"], mode="lines", line={"width": 3, "color": "#00b4ff"}, fill="tozeroy", fillcolor="rgba(0, 180, 255, 0.2)", name="Lines of Code", hovertemplate="<b>Date:</b> %{x}<br><b>Lines:</b> %{y:,}<extra></extra>"))
+    # Add markers for significant points (min, max, last)
+    min_idx = df["lines"].arg_min()
+    max_idx = df["lines"].arg_max()
+    min_point = df.slice(min_idx, 1).to_dicts()[0] if min_idx is not None else {}
+    max_point = df.slice(max_idx, 1).to_dicts()[0] if max_idx is not None else {}
+    last_point = df.slice(-1, 1).to_dicts()[0]
+
+    # Add markers for significant points
+    fig.add_trace(
+        go.Scatter(
+            x=[min_point["dtmExit"], max_point["dtmExit"], last_point["dtmExit"]],
+            y=[min_point["lines"], max_point["lines"], last_point["lines"]],
+            mode="markers",
+            marker={"size": [10, 14, 12], "color": ["#ff4f4f", "#4fff4f", "#4f4fff"], "line": {"width": 2, "color": "white"}, "symbol": ["circle", "star", "diamond"]},
+            name="Key Points",
+            hovertemplate="<b>%{text}</b><br>Date: %{x}<br>Lines: %{y:,}<extra></extra>",
+            text=[f"🔽 Min: {min_point['lines']:,} lines", f"🔼 Max: {max_point['lines']:,} lines", f"📊 Current: {last_point['lines']:,} lines"],
+        )
+    )
+
+    # Add annotation only for current point
+    # annotations = [
+    #     {"x": last_point['date'], "y": last_point['lines'], "text": f"📊 Current: {last_point['lines']:,} lines", "showarrow": True, "arrowhead": 2, "arrowsize": 1,
+    #         "arrowwidth": 2, "arrowcolor": "#ffffff", "font": {"size": 14, "color": "#ffffff"}, "bgcolor": "#00b4ff", "bordercolor": "#ffffff",
+    #         "borderwidth": 1, "borderpad": 4, "ax": 40, "ay": -40}
+    # ]
 
-if __name__ == "__main__":
-    app()
+    # Update layout with dark theme and customizations
+    fig.update_layout(
+        title={"text": "✨ Python Code Base Size Over Time ✨", "y": 0.95, "x": 0.5, "xanchor": "center", "yanchor": "top", "font": {"size": 24, "color": "white"}},
+        xaxis_title="Date 📅",
+        yaxis_title="Lines of Code 📝",
+        hovermode="closest",
+        template="plotly_dark",
+        plot_bgcolor="rgba(25, 25, 35, 1)",
+        paper_bgcolor="rgba(15, 15, 25, 1)",
+        font={"family": "Arial, sans-serif", "size": 14, "color": "white"},  # annotations=annotations,
+        autosize=True,
+        height=700,
+        margin={"l": 80, "r": 80, "t": 100, "b": 80},
+        xaxis={"showgrid": True, "gridcolor": "rgba(80, 80, 100, 0.2)", "showline": True, "linecolor": "rgba(200, 200, 255, 0.2)", "tickfont": {"size": 12}},
+        yaxis={"showgrid": True, "gridcolor": "rgba(80, 80, 100, 0.2)", "showline": True, "linecolor": "rgba(200, 200, 255, 0.2)", "tickformat": ",", "tickfont": {"size": 12}},
+    )
+
+    # Add range slider for date selection
+    fig.update_xaxes(rangeslider_visible=True, rangeslider_thickness=0.05)
+
+    # Save as interactive HTML and static image
+    plot_dir = Path.home().joinpath("tmp_results", "tmp_images", Path(repo_path).name)
+    plot_dir.mkdir(parents=True, exist_ok=True)
+
+    html_path = plot_dir.joinpath("code_size_evolution.html")
+    png_path = plot_dir.joinpath("code_size_evolution.png")
+
+    try:
+        fig.write_html(html_path, include_plotlyjs="cdn")
+    except Exception as e:
+        print(f"❌ Error saving HTML plot: {str(e)}")
+    try:
+        fig.write_image(png_path, width=1200, height=700, scale=2)
+    except Exception as e:
+        print(f"❌ Error saving PNG plot: {str(e)}")
+
+    print(f"🖼️ Interactive plot saved as {html_path}")
+    print(f"🖼️ Static image saved as {png_path}")
+    # Print statistics
+    print("\n📊 Repository Statistics:")
+    print(f"📚 Total commits analyzed: {len(df)}")
+    print(f"🔙 Initial line count: {df['lines'][-1]:,}")
+    print(f"🔜 Final line count: {df['lines'][0]:,}")
+    print(f"📈 Net change: {df['lines'][0] - df['lines'][-1]:,} lines")

machineconfig/scripts/python/{repos_helpers → helpers_repos}/sync.py

@@ -1,5 +1,4 @@
 from machineconfig.utils.path_extended import PathExtended
-from machineconfig.utils.code import write_shell_script_to_file
 import platform
 from pathlib import Path
 from rich.console import Console
@@ -56,11 +55,12 @@ def inspect_repos(repo_local_root: str, repo_remote_root: str):
 
     if platform.system() == "Windows":
         program = get_wt_cmd(wd1=PathExtended(repo_local_root), wd2=PathExtended(repo_local_root))
-        write_shell_script_to_file(shell_script=program)
-        return None
     elif platform.system() in ["Linux", "Darwin"]:
         program = get_zellij_cmd(wd1=PathExtended(repo_local_root), wd2=PathExtended(repo_remote_root))
-        write_shell_script_to_file(shell_script=program)
-        return None
     else:
         raise NotImplementedError(f"Platform {platform.system()} not implemented.")
+    import tempfile
+    with tempfile.NamedTemporaryFile(mode='w', suffix=".sh" if platform.system() != "Windows" else ".ps1", delete=False, encoding='utf-8') as temp_file:
+        temp_file.write(program)
+        temp_script_path = PathExtended(temp_file.name)
+    console.print(Panel(f"🚀 Launching repo inspection tool...\n\n[blue]{temp_script_path}[/blue]", border_style="blue"))

machineconfig/scripts/python/{sessions_helpers → helpers_sessions}/sessions_multiprocess.py

@@ -1,7 +1,6 @@
 
 
 from typing import Optional, Annotated
-from pathlib import Path
 import typer
 
 
@@ -10,23 +9,23 @@ def create_from_function(
         path: Annotated[str, typer.Option(..., "--path", "-p", help="Path to a Python or Shell script file or a directory containing such files")] = ".",
         function: Annotated[Optional[str], typer.Option(..., "--function", "-f", help="Function to run from the Python file. If not provided, you will be prompted to choose.")] = None,
 ):
-    from machineconfig.utils.ve import get_ve_activate_line, get_ve_path_and_ipython_profile
+    from machineconfig.utils.ve import get_ve_path_and_ipython_profile
     from machineconfig.utils.options import choose_from_options
     from machineconfig.utils.path_helper import match_file_name, sanitize_path
-    from machineconfig.utils.path_extended import PathExtended
     from machineconfig.utils.accessories import get_repo_root
+    from pathlib import Path
 
     path_obj = sanitize_path(path)
     if not path_obj.exists():
         suffixes = {".py"}
-        choice_file = match_file_name(sub_string=path, search_root=PathExtended.cwd(), suffixes=suffixes)
+        choice_file = match_file_name(sub_string=path, search_root=Path.cwd(), suffixes=suffixes)
     elif path_obj.is_dir():
-        from machineconfig.scripts.python.helpers_fire.helpers4 import search_for_files_of_interest
+        from machineconfig.utils.path_helper import search_for_files_of_interest
         print(f"🔍 Searching recursively for Python, PowerShell and Shell scripts in directory `{path_obj}`")
-        files = search_for_files_of_interest(path_obj)
+        files = search_for_files_of_interest(path_obj, suffixes={".py", ".sh", ".ps1"})
         print(f"🔍 Got #{len(files)} results.")
-        choice_file = choose_from_options(multi=False, options=files, fzf=True, msg="Choose one option")
-        choice_file = PathExtended(choice_file)
+        choice_file = choose_from_options(multi=False, options=files, tv=True, msg="Choose one option")
+        choice_file = Path(choice_file)
     else:
         choice_file = path_obj
 
@@ -36,10 +35,13 @@ def create_from_function(
     ve_root_from_file, ipy_profile = get_ve_path_and_ipython_profile(choice_file)
     if ipy_profile is None:
         ipy_profile = "default"
-    if ve_root_from_file is None:
-        raise ValueError(f"Could not determine virtual environment for file {choice_file}. Please ensure it is within a recognized project structure.")
-
-    _activate_ve_line = get_ve_activate_line(ve_root=ve_root_from_file)
+    # if ve_root_from_file is None:
+    #     raise ValueError(f"Could not determine virtual environment for file {choice_file}. Please ensure it is within a recognized project structure.")
+    # _activate_ve_line = get_ve_activate_line(ve_root=ve_root_from_file)
+    if ve_root_from_file is not None:
+        start_dir = Path(ve_root_from_file).parent
+    else:
+        start_dir = Path.cwd()
 
     # =========================  choosing function to run
     if function is None or function.strip() == "":
@@ -52,7 +54,11 @@ def create_from_function(
     from machineconfig.utils.schemas.layouts.layout_types import LayoutConfig
     layout: LayoutConfig = {"layoutName": "fireNprocess", "layoutTabs": []}
     for an_arg in range(num_process):
-        layout["layoutTabs"].append({"tabName": f"tab{an_arg}", "startDir": str(PathExtended.cwd()), "command": f"uv run -m fire {choice_file} {choice_function} --idx={an_arg} --idx_max={num_process}"})
+        layout["layoutTabs"].append({
+            "tabName": f"tab{an_arg}",
+            "startDir": str(start_dir),
+            "command": f"uv run python -m fire {choice_file} {choice_function} --idx={an_arg} --idx_max={num_process}"
+            })
     print(layout)
     run_zellij_layout(layout_config=layout)
 

machineconfig/scripts/python/helpers_utils/download.py

@@ -0,0 +1,150 @@
+
+
+from typing import Annotated, Optional
+import typer
+from pathlib import Path
+
+
+def download(
+    url: Annotated[Optional[str], typer.Argument(..., help="The URL to download the file from.")] = None,
+    decompress: Annotated[bool, typer.Option(..., "--decompress", "-d", help="Decompress the file if it's an archive.")] = False,
+    output: Annotated[Optional[str], typer.Option("--output", "-o", help="The output file path.")] = None,
+    output_dir: Annotated[Optional[str], typer.Option("--output-dir", help="Directory to place the downloaded file in.")] = None,
+) -> Optional["Path"]:
+    import subprocess
+    from urllib.parse import parse_qs, unquote, urlparse
+    from requests import Response
+    import requests
+    from pathlib import Path
+    if url is None:
+        typer.echo("❌ Error: URL is required.", err=True)
+        return None
+    if output is not None and output_dir is not None:
+        typer.echo("❌ Error: --output and --output-dir cannot be used together.", err=True)
+        return None
+    typer.echo(f"📥 Downloading from: {url}")
+
+    def _sanitize_candidate_filename(name: str) -> Optional[str]:
+        candidate = Path(name).name.strip()
+        if not candidate or candidate in {".", ".."}:
+            return None
+        return candidate
+
+    def _filename_from_content_disposition(header_value: Optional[str]) -> Optional[str]:
+        if header_value is None:
+            return None
+        parts = [segment.strip() for segment in header_value.split(";")]
+        for part in parts:
+            lower = part.lower()
+            if lower.startswith("filename*="):
+                value = part.split("=", 1)[1]
+                value = value.strip().strip('"')
+                if "''" in value:
+                    value = value.split("''", 1)[1]
+                decoded = unquote(value)
+                sanitized = _sanitize_candidate_filename(decoded)
+                if sanitized is not None:
+                    return sanitized
+            if lower.startswith("filename="):
+                value = part.split("=", 1)[1].strip().strip('"')
+                decoded = unquote(value)
+                sanitized = _sanitize_candidate_filename(decoded)
+                if sanitized is not None:
+                    return sanitized
+        return None
+
+    def _filename_from_url(source_url: str) -> Optional[str]:
+        parsed = urlparse(source_url)
+        url_candidate = _sanitize_candidate_filename(unquote(Path(parsed.path).name))
+        if url_candidate is not None:
+            return url_candidate
+        query_params = parse_qs(parsed.query, keep_blank_values=True)
+        for key, values in query_params.items():
+            lower_key = key.lower()
+            if "name" in lower_key or "file" in lower_key:
+                for value in values:
+                    sanitized = _sanitize_candidate_filename(unquote(value))
+                    if sanitized is not None:
+                        return sanitized
+        return None
+
+    def _resolve_download_path(request_url: str, response: Response, requested_output: Optional[str], requested_output_dir: Optional[str]) -> Path:
+        if requested_output is not None:
+            return Path(requested_output)
+        header_candidate = _filename_from_content_disposition(response.headers.get("content-disposition"))
+        if header_candidate is None:
+            header_candidate = _filename_from_url(response.url)
+        if header_candidate is None:
+            header_candidate = _filename_from_url(request_url)
+        if header_candidate is None:
+            header_candidate = "downloaded_file"
+        if requested_output_dir is not None:
+            return Path(requested_output_dir) / header_candidate
+        return Path(header_candidate)
+
+    try:
+        with requests.get(url, allow_redirects=True, stream=True, timeout=60) as response:
+            response.raise_for_status()
+            download_path = _resolve_download_path(url, response, output, output_dir)
+            download_path.parent.mkdir(parents=True, exist_ok=True)
+            total_size_header = response.headers.get("content-length", "0")
+            try:
+                total_size = int(total_size_header)
+            except (TypeError, ValueError):
+                total_size = 0
+            if total_size <= 0:
+                with open(download_path, "wb") as file_handle:
+                    file_handle.write(response.content)
+            else:
+                downloaded = 0
+                chunk_size = 8192 * 40
+                with open(download_path, "wb") as file_handle:
+                    for chunk in response.iter_content(chunk_size=chunk_size):
+                        if not chunk:
+                            continue
+                        file_handle.write(chunk)
+                        downloaded += len(chunk)
+                        progress = (downloaded / total_size) * 100
+                        typer.echo(f"\r⏬ Progress: {progress:.1f}% ({downloaded}/{total_size} bytes)", nl=False)
+                typer.echo()
+    except requests.exceptions.RequestException as exception:
+        typer.echo(f"❌ Download failed: {exception}", err=True)
+        return None
+    except OSError as exception:
+        typer.echo(f"❌ File write error: {exception}", err=True)
+        return None
+
+    typer.echo(f"✅ Downloaded to: {download_path}")
+    result_path: Path = download_path
+    if decompress:
+        typer.echo(f"📦 Decompressing: {download_path}")
+        base_name = download_path.name.split(".", maxsplit=1)[0]  # ouch decompresses all (e.g. .tar.gz) in one go.
+        if base_name in {"", ".", ".."}:
+            base_name = "extracted"
+        extract_dir = download_path.parent / base_name
+        extract_dir.mkdir(parents=True, exist_ok=True)
+        try:
+            subprocess.run(
+                ["ouch", "decompress", str(download_path), "--dir", str(extract_dir)],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            typer.echo(f"✅ Decompressed to: {extract_dir}")
+            if download_path.exists():
+                download_path.unlink()
+                typer.echo(f"🗑️  Removed archive: {download_path}")
+            result_path = extract_dir
+        except subprocess.CalledProcessError as exception:
+            typer.echo(f"❌ Decompression failed: {exception.stderr}", err=True)
+            return None
+        except FileNotFoundError:
+            typer.echo("❌ Error: ouch command not found. Please install ouch.", err=True)
+            typer.echo("💡 Install with: cargo install ouch", err=True)
+            return None
+
+    return result_path.resolve()
+
+
+if __name__ == "__main__":
+    pass