Add download support and binary build automation

Introduce repository download functionality in the CLI, add local PyInstaller build tooling, and add a GitHub Actions workflow for cross-platform binary artifacts.

Co-Authored-By: Oz <oz-agent@warp.dev>

Author: harrypm

.github/workflows/build-binaries.yml

@@ -0,0 +1,68 @@
+name: Build Cross-Platform Binaries
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  build-binaries:
+    name: Build on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - macos-latest
+          - windows-latest
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r requirements-build.txt
+
+      - name: Build binary
+        run: pyinstaller --clean --onefile --name ia-interact ia-interact.py
+
+      - name: Prepare platform artifact
+        run: |
+          python - <<'PY'
+          import os
+          import pathlib
+          import shutil
+
+          runner_os = os.environ["RUNNER_OS"]
+          ext = ".exe" if runner_os == "Windows" else ""
+          source_path = pathlib.Path("dist") / f"ia-interact{ext}"
+          if not source_path.exists():
+              raise SystemExit(f"Build output not found: {source_path}")
+
+          suffix_map = {"Linux": "linux", "Windows": "windows", "macOS": "macos"}
+          suffix = suffix_map.get(runner_os, runner_os.lower())
+          artifacts_dir = pathlib.Path("artifacts")
+          artifacts_dir.mkdir(parents=True, exist_ok=True)
+          destination_path = artifacts_dir / f"ia-interact-{suffix}{ext}"
+          shutil.copy2(source_path, destination_path)
+          print(f"Prepared artifact: {destination_path}")
+          PY
+
+      - name: Upload binary artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ia-interact-${{ runner.os }}
+          path: artifacts/*
+          if-no-files-found: error

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+build/
+dist/
+*.spec
+.venv/
+.venv-build/

README.md

@@ -3,7 +3,7 @@
 
 An interactive command-line tool for managing Internet Archive repositories. 
 
-Use this script to list files, upload files, delete files, move files, and create new repositories with detailed metadata input. 
+Use this script to list files, upload files, download files, delete files, move files, and create new repositories with detailed metadata input. 
 
 
 ## Table of Contents
@@ -38,8 +38,7 @@ Use this script to list files, upload files, delete files, move files, and creat
 
 
 ## Features
-
-- **Interactive Menu:** Choose options to list files, upload files, delete or move files, or create a new repository.
+- **Interactive Menu:** Choose options to list files, upload files, download files, delete or move files, or create a new repository.
 - **Test Mode & Permanent Mode:** Run in simulation (Test Mode, where no changes are made) or execute actual changes (Permanent Mode).
 - **Metadata Support:** Input metadata including title, description, creator, date, language, license URL, collection, subject tags, and test item status.
 - **Collection Options:** Supports collections such as `community`, `opensource`, `texts`, `movies`, `audio`, `image`, `etree`, `folksoundomy`, `games`, and `software`.
@@ -138,6 +137,36 @@ Replace `"your-access-key"` and `"your-secret-key"` with your actual keys.
 
     echo $S3_ACCESS_KEY
     echo $S3_SECRET_KEY
+### 5. Build a Local Binary
+
+Install build dependencies:
+
+    pip3 install -r requirements-build.txt
+
+Build a single-file executable:
+
+    pyinstaller --clean --onefile --name ia-interact ia-interact.py
+
+The binary will be output to:
+
+    dist/ia-interact
+
+On Windows, the file will be:
+
+    dist/ia-interact.exe
+
+# GitHub Actions: Cross-Platform Binaries
+
+This repository includes:
+
+    .github/workflows/build-binaries.yml
+
+The workflow builds platform binaries for:
+- Linux (`ubuntu-latest`)
+- macOS (`macos-latest`)
+- Windows (`windows-latest`)
+
+Each run uploads build artifacts with platform-specific names.
 
 
 # Usage
@@ -165,6 +194,7 @@ When the script runs, it displays an interactive menu with the following options
 
 - **List Files:** Display the contents of an existing repository.
 - **Upload Files:** Add files to a repository.
+- **Download Files:** Download one file or all files from a repository to a local folder.
 - **Delete/Move Files:** Manage files within a repository.
 - **Create a New Repository:** Upload an entire folder and configure repository metadata.
 
@@ -212,6 +242,7 @@ During repository creation, you will be prompted to:
 - **Listing Repository Contents:** Retrieve and display the contents of a repository using the metadata API.
 - **Deleting Files:** Remove specified files from a repository.
 - **Moving Files:** Change a file’s location within a repository by copying it and then deleting the original.
+- **Downloading Files:** Download a single file or all files from a repository to a local path.
 - **Creating a New Repository:** Upload a folder as a new repository and submit metadata.
 - **User Interaction:** Offers an interactive menu with a help option, test mode (simulation) vs. permanent mode, and filtering to avoid showing files from ".thumbs" directories.
 
@@ -320,10 +351,10 @@ This script uses the Internet Archive’s S3-compatible interface and Metadata A
 - **Purpose:**  
   Serves as the entry point of the script with an interactive menu.
 - **Key Features:**
-  - **Main Menu:** Displays options for uploading, listing, deleting, moving files, creating a repository, or viewing help.
+  - **Main Menu:** Displays options for uploading, listing, deleting, moving, and downloading files, creating a repository, or viewing help.
   - **Conditional Prompts:**  
-    - **For Existing Repositories (options 1–4):** Prompts for the repository URL after the option selection.
-    - **For Folder-based Repository Creation (option 5):** Gathers folder path, mode, and metadata.
+    - **For Existing Repositories (options 1–5):** Prompts for the repository URL after the option selection.
+    - **For Folder-based Repository Creation (option 6):** Gathers folder path, mode, and metadata.
   - **Action Dispatch:** Calls the corresponding function based on the user’s selection.
 
 

build-binary.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+VENV_PATH="$SCRIPT_DIR/.venv-build"
+DIST_PATH="$SCRIPT_DIR/dist"
+BUILD_PATH="$SCRIPT_DIR/build"
+
+if [ ! -d "$VENV_PATH" ]; then
+  python3 -m venv "$VENV_PATH"
+fi
+"$VENV_PATH/bin/python" -m pip install --upgrade pip
+"$VENV_PATH/bin/python" -m pip install -r "$SCRIPT_DIR/requirements-build.txt"
+"$VENV_PATH/bin/pyinstaller" \
+  --clean \
+  --onefile \
+  --name ia-interact \
+  --distpath "$DIST_PATH" \
+  --workpath "$BUILD_PATH" \
+  --specpath "$SCRIPT_DIR" \
+  "$SCRIPT_DIR/ia-interact.py"
+
+printf 'Binary created at %s\n' "$SCRIPT_DIR/dist/ia-interact"

ia-interact.py

@@ -4,6 +4,7 @@
 from tqdm import tqdm
 from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
+from urllib.parse import quote
 
 def get_repo_identifier(repo_link):
     """
@@ -166,6 +167,88 @@ def move_file(identifier, file_name, source_dir, target_dir):
     except Exception as e:
         print("Error during file move (copy-delete):", e)
         return False
+def download_file_with_progress(identifier, file_name, destination_dir):
+    """
+    Downloads a file from an Internet Archive repository with progress tracking.
+    """
+    safe_relative_path = os.path.normpath(file_name).lstrip("/\\")
+    if safe_relative_path.startswith(".."):
+        print(f"Skipping unsafe file path: {file_name}")
+        return False
+
+    download_url = f"https://archive.org/download/{identifier}/{quote(file_name, safe='/')}"
+    output_path = os.path.join(destination_dir, safe_relative_path)
+    output_folder = os.path.dirname(output_path)
+
+    if output_folder:
+        os.makedirs(output_folder, exist_ok=True)
+
+    try:
+        response = requests.get(download_url, stream=True, timeout=(60, 600))
+        if response.status_code != 200:
+            print(f"Error downloading {file_name}: {response.status_code} {response.reason}")
+            return False
+
+        total_size = int(response.headers.get("content-length", 0))
+        progress_total = total_size if total_size > 0 else None
+
+        with tqdm(total=progress_total, unit="B", unit_scale=True, desc=f"Downloading {os.path.basename(file_name)}") as pbar:
+            with open(output_path, "wb") as f:
+                for chunk in response.iter_content(chunk_size=1024 * 1024):
+                    if not chunk:
+                        continue
+                    f.write(chunk)
+                    pbar.update(len(chunk))
+
+        print(f"Downloaded '{file_name}' to '{output_path}'")
+        return True
+    except requests.exceptions.RequestException as e:
+        print(f"Request error during download: {e}")
+        return False
+    except Exception as e:
+        print(f"Unexpected download error: {e}")
+        return False
+
+def download_repository_files(identifier):
+    """
+    Downloads one or all files from a repository.
+    """
+    file_list = list_repository_files(identifier)
+    if not file_list:
+        return
+
+    destination_dir_input = input("Enter destination folder (leave blank for current directory): ").strip().strip('\"').strip("'")
+    destination_dir = os.path.abspath(os.path.expanduser(destination_dir_input)) if destination_dir_input else os.getcwd()
+
+    try:
+        os.makedirs(destination_dir, exist_ok=True)
+    except OSError as e:
+        print(f"Unable to create/access destination folder: {e}")
+        return
+
+    print("\nDownload Options:")
+    print("1. Download a single file")
+    print("2. Download all files")
+    download_choice = input("Enter your choice (1 or 2): ").strip()
+
+    if download_choice == "1":
+        print("Enter the number of the file to download:")
+        try:
+            index = int(input().strip()) - 1
+            if 0 <= index < len(file_list):
+                download_file_with_progress(identifier, file_list[index], destination_dir)
+            else:
+                print("Invalid index.")
+        except ValueError:
+            print("Invalid input.")
+    elif download_choice == "2":
+        successful_downloads = 0
+        for file_name in file_list:
+            if download_file_with_progress(identifier, file_name, destination_dir):
+                successful_downloads += 1
+        print(f"\nDownloaded {successful_downloads} of {len(file_list)} files.")
+    else:
+        print("Invalid choice. Exiting download menu.")
 
 def create_rules_file(folder_path):
     """
@@ -293,9 +376,11 @@ def print_help():
    - List files and choose one to delete.
 4. Move a file within a repository:
    - Copy a file to a new directory using x-amz-copy-source, then delete the original.
-5. Create or access a repository from a folder:
+5. Download files from a repository:
+   - Download one or all files to a local destination folder.
+6. Create or access a repository from a folder:
    - Upload an entire folder as a new repository with metadata and mode selection.
-6. Help:
+7. Help:
    - Display this help information.
 
 Instructions:
@@ -315,14 +400,15 @@ def main():
     print("2. List files in a repository")
     print("3. Delete a file from a repository")
     print("4. Move a file within a repository")
-    print("5. Create or access a repository from a folder")
-    print("6. Help")
-    choice = input("Enter your choice (1-6): ").strip()
+    print("5. Download files from a repository")
+    print("6. Create or access a repository from a folder")
+    print("7. Help")
+    choice = input("Enter your choice (1-7): ").strip()
 
-    if choice == "6":
+    if choice == "7":
         print_help()
         main()
-    elif choice == "5":
+    elif choice == "6":
         folder_path = input("Enter the folder path to upload as a repository: ").strip().strip('\"').strip('\'')
         if not os.path.isdir(folder_path):
             print("Invalid folder path. Please check if the directory exists and is accessible.")
@@ -345,7 +431,7 @@ def main():
             print("Repository identifier is required.")
             return
         initialize_repository(folder_path, identifier, metadata, mode)
-    elif choice in ("1", "2", "3", "4"):
+    elif choice in ("1", "2", "3", "4", "5"):
         repo_link = input("Enter the Internet Archive repository link: ").strip()
         identifier = get_repo_identifier(repo_link)
         if not identifier:
@@ -408,6 +494,8 @@ def main():
                     print("Invalid index.")
             except ValueError:
                 print("Invalid input.")
+        elif choice == "5":
+            download_repository_files(identifier)
     else:
         print("Invalid choice. Exiting.")
 

requirements-build.txt

@@ -0,0 +1,2 @@
+-r requirements.txt
+pyinstaller>=6.0.0

requirements.txt

@@ -0,0 +1,2 @@
+requests>=2.31.0
+tqdm>=4.66.0