feat: Standalone App Packaging & Setup Flow

.github/workflows/build.yml

@@ -0,0 +1,62 @@
+name: Build
+
+on:
+  push:
+    branches: [ main ]
+    tags: [ 'v*' ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    name: Build on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: write
+    strategy:
+      fail-fast: false
+      matrix:
+        # macos-13 is the last Intel runner
+        # macos-14 is Apple Silicon (M1)
+        os: [ubuntu-latest, windows-latest, macos-14]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+
+    - name: Set up Python
+      run: uv python install 3.12
+
+    - name: Install dependencies
+      run: uv sync
+
+    - name: Build with PyInstaller
+      run: uv run python build_app.py
+
+    - name: Zip Build Output (Unix)
+      if: runner.os != 'Windows'
+      run: |
+        cd dist
+        zip -r ../gmail-cleaner-${{ matrix.os }}.zip gmail-cleaner/
+
+    - name: Zip Build Output (Windows)
+      if: runner.os == 'Windows'
+      run: |
+        Compress-Archive -Path dist/gmail-cleaner -DestinationPath gmail-cleaner-${{ matrix.os }}.zip
+
+    - name: Upload Artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: gmail-cleaner-${{ matrix.os }}
+        path: gmail-cleaner-${{ matrix.os }}.zip
+        if-no-files-found: error
+        retention-days: 30
+
+    - name: Release
+      uses: softprops/action-gh-release@v2
+      if: startsWith(github.ref, 'refs/tags/')
+      with:
+        files: gmail-cleaner-${{ matrix.os }}.zip
+

.gitignore

@@ -29,5 +29,6 @@ IMPROVEMENTS.md
 htmlcov/
 coverage.xml
 
-# GitHub Copilot instructions (user specific)
-.github/copilot-instructions.md
+# PyInstaller
+build/
+dist/

AGENTS.md

@@ -0,0 +1,80 @@
+# AGENTS.md - Development Guide
+
+**Generated:** Thu, Feb 12, 2026
+**Branch:** main
+
+## OVERVIEW
+Privacy-focused Gmail cleanup tool using **FastAPI** (Python 3.9+) and **Vanilla JS**. Runs locally/Docker, no external database.
+
+## STRUCTURE
+```
+.
+├── app/               # FastAPI backend
+│   ├── api/           # Routes (actions.py, status.py)
+│   ├── core/          # Config & State (Global variables)
+│   ├── models/        # Pydantic schemas
+│   └── services/      # Business logic
+│       ├── auth.py    # OAuth flow & Credential mgmt (God Object)
+│       └── gmail/     # Gmail API operations (Scan, Delete, Archive)
+├── static/            # Frontend (Vanilla JS)
+│   ├── js/            # Logic (Module pattern, global namespace)
+│   └── css/           # Styles
+├── templates/         # HTML (Jinja2)
+└── tests/             # Pytest suite
+    ├── unit/          # Isolated tests (Mocked)
+    └── integration/   # [EMPTY] Missing integration tests
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| **Auth/Login** | `app/services/auth.py` | Handles OAuth, tokens, local server. Complex. |
+| **Email Logic** | `app/services/gmail/` | Modular operations (scan, delete, etc.). |
+| **Frontend UI** | `static/js/` | Ad-hoc framework. `main.js` orchestrates. |
+| **State** | `app/core/state.py` | Global thread-safe state for async tasks. |
+| **API Routes** | `app/api/` | `actions.py` (POST), `status.py` (GET), `setup.py` (Setup). |
+| **Config** | `app/core/config.py` | Settings via Pydantic (`.env`). |
+
+## CODE MAP (Key Symbols)
+| Symbol | Type | Location | Role |
+|--------|------|----------|------|
+| `GmailService` | Class | `app/services/auth.py` | Wrapper for Gmail API resource. |
+| `get_gmail_service` | Func | `app/services/auth.py` | **CRITICAL**. Retrieves/refreshes auth. |
+| `process_scan` | Func | `app/services/gmail/scan.py` | Core scanning logic. |
+| `GmailCleaner` | Obj | `static/js/main.js` | Global frontend namespace (State/UI). |
+| `app` | Var | `app/main.py` | FastAPI application instance. |
+
+## CONVENTIONS
+- **State**: Backend uses `app.core.state` global variables for progress tracking.
+- **Frontend**: "Module Pattern" with global `GmailCleaner`. No build step.
+- **Async**: Backend is async (FastAPI), but uses `threading` for background tasks.
+- **Testing**:
+  - `pytest` with `pytest-asyncio`.
+  - **Mocks**: Aggressive mocking of `credentials.json` in `conftest.py`.
+  - **Fixtures**: `mock_gmail_auth` (autouse) prevents real auth in tests.
+
+## ANTI-PATTERNS (THIS PROJECT)
+- **NO SECRETS**: NEVER commit `credentials.json`, `token.json`, or `.env`.
+- **No `try/except`**: Use `HTTPException` or custom exceptions.
+- **Frontend Coupling**: Logic/UI tightly coupled in `labels.js`/`delete.js`.
+- **Global State**: Frontend relies on global `window.GmailCleaner`.
+
+## COMMANDS
+```bash
+# Dev
+uv sync
+uv run python main.py
+
+# Test
+uv run pytest
+uv run pytest tests/unit/services/auth/
+
+# Lint
+uv run ruff check .
+uv run pyright
+```
+
+## NOTES
+- **Auth Flow**: Uses a local server callback. Docker requires port mapping.
+- **Data Persistence**: `token.json` stored in `./data/` (Docker volume) or platform-specific data dir via `platformdirs`.
+- **Concurrency**: `app/services/gmail` uses batch requests (performance).

GMAIL_SERVICES_ANALYSIS.md

@@ -0,0 +1,38 @@
+# Deep Dive Analysis: `app/services/gmail`
+
+## 1. Overview
+The `app/services/gmail` directory is well-structured and modular. It follows a clear separation of concerns, with each file handling a specific aspect of Gmail operations (scanning, deleting, archiving, etc.). The `__init__.py` file acts as a clean facade, exposing necessary functions while hiding internal implementation details.
+
+## 2. Pattern Consistency
+The codebase demonstrates high consistency in the following areas:
+
+*   **State Management**: All modules consistently use the global `state` object from `app.core.state` to track progress, store results, and handle errors. This ensures a unified way of communicating status to the frontend.
+*   **Service Retrieval**: Every module retrieves the Gmail service using `get_gmail_service()` from `app.services.auth`, handling potential errors in a uniform way.
+*   **Batch Processing**: Operations like scanning and deleting consistently use Gmail API's batch capabilities (`new_batch_http_request` or `batchModify`) to optimize performance and respect rate limits.
+*   **Status Reporting**: Each module provides a `get_<operation>_status()` function that returns a copy of the relevant state, maintaining a consistent interface for status polling.
+*   **Error Handling**: `try-except` blocks are used consistently to catch exceptions, update the state with the error message, and mark the operation as done.
+
+## 3. Shared Helpers
+`app/services/gmail/helpers.py` is effectively used to share common logic, preventing code duplication. Key helpers include:
+*   `build_gmail_query`: Centralizes query construction logic.
+*   `get_sender_info` & `get_subject`: Standardizes header parsing.
+*   `get_unsubscribe_from_headers`: Encapsulates the logic for finding unsubscribe links.
+*   `validate_unsafe_url`: Provides shared security validation.
+
+## 4. "God Objects" & Complexity
+While most files are focused, a few areas show signs of high complexity:
+
+*   **`app/services/auth.py` (External to `gmail` dir but critical)**: This file is a "God Object" candidate (685 lines). The `get_gmail_service` function contains a massive nested `run_oauth` function that handles the entire OAuth flow, including starting a local HTTP server. This logic should ideally be extracted into a separate `OAuthManager` class or module.
+*   **`app/services/gmail/delete.py`**: This file (439 lines) handles both the *scanning* of senders for deletion and the *actual deletion* (both single sender and bulk). Splitting this into `delete_scan.py` and `delete_action.py` would improve maintainability and separation of concerns.
+
+## 5. Circular Dependencies
+**Status: Clean.**
+No circular dependencies were found. The dependency graph is unidirectional and healthy:
+*   `app/services/gmail/*` imports `app.core.state`, `app.services.auth`, and `app.services.gmail.helpers`.
+*   `app/services/auth` imports `app.core.state` and `app.core.settings`.
+*   `app/core/state` has no internal dependencies.
+*   `app/services/gmail/__init__.py` imports from submodules but submodules do not import back from `__init__`.
+
+## 6. Recommendations
+1.  **Refactor `app/services/auth.py`**: Extract the OAuth flow logic into a dedicated handler to reduce the size and complexity of the auth service.
+2.  **Split `app/services/gmail/delete.py`**: Separate the scanning logic (`scan_senders_for_delete`) from the deletion logic (`delete_emails_by_sender`, `delete_emails_bulk`) to align with the single-responsibility principle.

README.md

@@ -11,6 +11,17 @@ A **free**, privacy-focused tool to bulk unsubscribe from emails, delete emails
 
 > **No Subscription Required - Free Forever**
 
+## 🚀 Download & Install
+
+The easiest way to use Gmail Cleaner is to download the standalone app for your operating system.
+
+1.  Go to the [Releases](https://github.com/Gururagavendra/gmail-cleaner/releases) page.
+2.  Download the version for your OS:
+    *   **Windows**: `.exe` installer
+    *   **macOS**: `.dmg` or `.app`
+    *   **Linux**: `AppImage` or binary
+3.  Launch the app and follow the on-screen instructions to upload your `credentials.json`.
+
 ## Features
 
 | Feature | Description |
@@ -76,6 +87,10 @@ Lets make this tool a better one by improving as much as possible, All features
 
 **Important**: You must create your **OWN** Google Cloud credentials. This app doesn't include pre-configured OAuth - that's what makes it privacy-focused! Each user runs their own instance with their own credentials.
 
+Once you have your `credentials.json`, you can either:
+- **Standalone App**: Simply upload it via the app's user interface.
+- **Docker/Python**: Place it in the project root folder.
+
 ### 1. Get Google OAuth Credentials
 
 **Video Tutorial**: [Watch on YouTube](https://youtu.be/CmOWn8Tm5ZE) for a visual walkthrough
@@ -129,7 +144,14 @@ cd gmail-cleaner
 
 ## Usage
 
-### Option A: Docker (Recommended)
+### Option A: Standalone App (Recommended)
+
+1.  Download and install the app from the [Releases](https://github.com/Gururagavendra/gmail-cleaner/releases) page.
+2.  Launch the application.
+3.  When prompted, upload your `credentials.json` file.
+4.  Click **"Sign In"** and follow the OAuth flow in your browser.
+
+### Option B: Docker (Alternative / Server Mode)
 
 1. Pull the latest image and start the container:
 ```bash
@@ -193,7 +215,7 @@ rm -f ./data/token.json
 docker compose up
 ```
 
-### Option B: Python (with uv)
+### Option C: Python (Development)
 
 ```bash
 uv sync
@@ -392,6 +414,26 @@ This error occurs when you try to use an **IP address** in the redirect URI (e.g
 
 **Remember:** The redirect URI in Google Cloud Console must exactly match what you set in `OAUTH_HOST` + port.
 
+## 🛠️ Development & Building
+
+If you want to build the standalone app yourself:
+
+1.  Install [Python 3.9+](https://www.python.org/downloads/) and [uv](https://docs.astral.sh/uv/).
+2.  Clone the repository:
+    ```bash
+    git clone https://github.com/Gururagavendra/gmail-cleaner.git
+    cd gmail-cleaner
+    ```
+3.  Install dependencies:
+    ```bash
+    uv sync
+    ```
+4.  Build the app:
+    ```bash
+    uv run python build_app.py
+    ```
+    The built application will be available in the `dist/` folder.
+
 ## Contributing
 
 PRs welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) first.

app/api/__init__.py

@@ -2,5 +2,6 @@
 
 from .status import router as status_router
 from .actions import router as actions_router
+from .setup import router as setup_router
 
-__all__ = ["status_router", "actions_router"]
+__all__ = ["actions_router", "setup_router", "status_router"]

app/api/setup.py

@@ -0,0 +1,69 @@
+"""
+Setup API Routes
+----------------
+Endpoints for initial application setup (uploading credentials).
+"""
+
+import json
+import logging
+import os
+
+from fastapi import APIRouter, File, HTTPException, UploadFile, status
+
+from app.core import settings
+
+router = APIRouter(prefix="/api", tags=["Setup"])
+logger = logging.getLogger(__name__)
+
+
+@router.post("/setup")
+async def setup_credentials(file: UploadFile = File(...)):
+    """Upload credentials.json file."""
+    # Check if credentials already exist
+    if os.path.exists(settings.credentials_file):
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Credentials file already exists. Please delete it manually to upload a new one.",
+        )
+
+    try:
+        content = await file.read()
+
+        # Validate JSON structure
+        try:
+            data = json.loads(content)
+        except json.JSONDecodeError:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Invalid JSON file",
+            )
+
+        # Validate content (must be Google OAuth credentials)
+        if "installed" not in data and "web" not in data:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Invalid credentials file. Must contain 'installed' or 'web' client configuration.",
+            )
+
+        # Ensure directory exists
+        os.makedirs(
+            os.path.dirname(os.path.abspath(settings.credentials_file)), exist_ok=True
+        )
+
+        # Save to settings.credentials_file
+        with open(settings.credentials_file, "wb") as f:
+            f.write(content)
+
+        logger.info(f"Credentials uploaded successfully to {settings.credentials_file}")
+        return {
+            "message": "Credentials uploaded successfully",
+        }
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.exception("Error uploading credentials")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to upload credentials. Please check server logs.",
+        ) from e