# Users Cleanup Tool

A command-line utility designed to process user lists from CSV files, handle Auth0 user deactivation/deletion, and generate Neo4j migration scripts. The tool utilizes `asyncio` for concurrent processing and `uv` for dependency management.

## 📋 Prerequisites

- **Python 3.13+**
- **[uv](https://github.com/astral-sh/uv)**: An extremely fast Python package installer and resolver.

## 🚀 Installation

**Install dependencies:**
   You can use the provided Makefile to setup the environment.
   ```bash
   make install
   ```
   *For developers (includes linting/typing tools):*
   ```bash
   make install_dev
   ```

## ⚙️ Configuration

Before running the tool, you must configure the environment variables (Auth0 credentials, etc.).

1. **Create the environment file:**
   Copy the shadow configuration file to a real `.env` file.
   ```bash
   cp .env.shadow .env
   ```

2. **Populate credentials:**
   Open `.env` in your editor and fill in the required values (e.g., `AUTH0_CLIENT_ID`, `AUTH0_CLIENT_SECRET`, `AUTH0_TENANT`, etc.).

## ⚡️ Happy Path Usage

The subcommands are designed to be run sequentially. The output of one step serves as the default input for the next step, allowing you to run the full pipeline with minimal arguments.

```bash
# 1. Parse and validate the raw CSV (Saves to result/validated.csv)
./cleanup_users.py prepare --fi=users_list.csv

# 2. Generate Neo4j migration script (Reads from result/validated.csv)
./cleanup_users.py create_migration --task_id=JIRA-1234

# 3. Deactivate/Delete users in Auth0 (Reads from result/validated.csv)
./cleanup_users.py delete_auth0_users
```

## 🛠 Detailed Usage

The tool is executed via `cleanup_users.py`. Since the script uses a `uv run` shebang, you can execute it directly if it has permission, or via `uv run`.

**Global Options:**
- `-h, --help`: Show help message.
- `-v, --verbose`: Enable verbose logging (DEBUG level).

### 1. Prepare Users
Reads a raw CSV file, processes/validates the data, and outputs a clean CSV.

```bash
./cleanup_users.py prepare --fi <input_file> [options]
```

| Argument | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `--fi` | Path | **Required** | Path to the raw input CSV. |
| `--fo` | Path | `result/validated.csv` | Path where valid results are saved. |
| `--email-key` | String | `email` | The column header name for emails in the input CSV. |
| `--concurrency` | Int | `10` | Number of concurrent processing tasks. |

**Example:**
```bash
./cleanup_users.py prepare --fi raw_users.csv --email-key "User Email"
```

### 2. Delete Auth0 Users
Takes the validated CSV and performs deletion/deactivation operations against Auth0.

```bash
./cleanup_users.py delete_auth0_users [options]
```

| Argument | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `--fi` | Path | `result/validated.csv` | Path to the validated input CSV. |
| `--fo` | Path | `result/delete_auth0_users.csv` | Path for the operation results. |
| `--concurrency` | Int | `10` | Number of concurrent API requests. |
|`-y`, `--yes` | Flag | False | Skip confirmation prompt. |

**Example:**
```bash
./cleanup_users.py delete_auth0_users --concurrency 20
```

### 3. Create Migration
Generates a Neo4j (Cypher) migration script based on the processed user list.

```bash
./cleanup_users.py create_migration --task_id <JIRA_ID> [options]
```

| Argument | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `--task_id` | String | **Required** | JIRA task ID (used for audit fields in Cypher). |
| `--fi` | Path | `result/validated.csv` | Path to the validated input CSV. |
| `--fo` | Path | `result/migration.cypher` | Path to save the generated Cypher script. |

**Example:**
```bash
./cleanup_users.py create_migration --task_id "PROJECT-1234"
```

## 💻 Development

This project uses a `Makefile` to simplify common development tasks.

### Available Commands

| Command | Description |
| :--- | :--- |
| `make help` | Show available make targets. |
| `make install` | Install production dependencies only. |
| `make install_dev` | Install all dependencies (including dev tools). |
| `make format` | Format code using `ruff`. |
| `make lint` | Lint code using `ruff`. |
| `make lint_fix` | Lint and automatically fix issues with `ruff`. |
| `make type_check` | Run static type checking with `mypy`. |
| `make check` | Run both linting and type checking (CI friendly). |