wrkflovv 0.1.3
Work Flow Simulator - Keystroke simulation tool for fraud detection research
Requires Python: >=3.10
Keywords: typing, simulation, research, fraud-detection, tui

# wrkflovv

A keystroke simulation tool designed for fraud detection research. Simulates human-like typing behavior by automating the process of typing content from source files at realistic speeds with authentic behavioral patterns.

## Features

- **Realistic Typing Simulation** - Variable WPM with human-like delays and variance
- **Typo Simulation** - Automatic typos with corrections using adjacent key mapping
- **Burst Typing** - Variable speed patterns within sessions
- **Idle Periods** - Simulated work interruptions for authentic behavior
- **Dual Interface** - Both interactive TUI and headless CLI modes
- **Auto-Detection** - Automatically finds source files in current directory
- **File Selection** - Select specific files to type using spacebar
- **Live IDE Preview** - Opens temp files in VS Code/IDE to watch typing in real-time
- **Stealth Mode** - Hide the TUI with a fake process list (F9)
- **Persistent Configuration** - Settings saved between sessions

## Installation

### Requirements

- Python 3.10 or higher
- Linux or Windows

### Quick Install (One-liner)

```bash
curl -sSL https://raw.githubusercontent.com/Umar-Khan-Yousafzai/Workflovv-TUI/main/install.sh | bash
```

### Install from PyPI (Recommended)

```bash
pip install wrkflovv
```

### Install from GitHub (Latest)

```bash
pip install git+https://github.com/Umar-Khan-Yousafzai/Workflovv-TUI.git
```

### Install from Source (Development)

```bash
# Clone the repository
git clone https://github.com/Umar-Khan-Yousafzai/Workflovv-TUI.git
cd Workflovv-TUI

# Install in editable mode
pip install -e .

# Or install normally
pip install .
```

### Verify Installation

```bash
wrkflovv --version
```

### Uninstall

```bash
pip uninstall wrkflovv
```

## Quick Start

### Interactive Mode (Recommended)

```bash
# Navigate to your project directory
cd /path/to/your/project

# Launch wrkflovv - it auto-detects files!
wrkflovv
```

Then in the TUI:
1. Use `↑`/`↓` to navigate the file list
2. Press `SPACE` to select files (or `A` for all)
3. Press `ENTER` to start typing!
4. Watch the magic in VS Code!

### Headless Mode

```bash
# Run without TUI
wrkflovv run /path/to/file.py
```

---

## Usage Modes

### Interactive Mode (TUI)

Launch the full interactive terminal interface with real-time visualization.

```bash
wrkflovv
```

#### TUI Controls

| Key | Action |
|-----|--------|
| `F10` | Start typing simulation |
| `F2` | Stop typing simulation |
| `F3` | Pause/Resume |
| `F5` | Refresh/rescan files in directory |
| `F9` | Toggle Stealth Mode |
| `+` / `=` | Increase WPM by 5 |
| `-` | Decrease WPM by 5 |
| `SPACE` | Select/deselect file (in file list) |
| `ENTER` | **Start typing** (if files are selected) |
| `A` | Select all files |
| `N` | Deselect all files |
| `Ctrl+C` | Quit |
| `Ctrl+Q` | Quit |

#### TUI Features

- **Auto-Detection** - Automatically scans current directory for source files on launch
- **File Selection** - Use SPACE to select which files to type (checkbox UI)
- **Live IDE Preview** - Creates temp file and opens in VS Code to watch typing live
- **Header Bar** - Shows app title, current status, active file, and live stats
- **File List** - Displays all detected files with selection checkboxes
- **Typing Preview** - Shows the last 500 characters being typed
- **Status Bar** - Progress bar, WPM display, and session statistics
- **Stealth Mode** - Press F9 to hide TUI and show fake system processes

#### Status Indicators

| Status | Color | Meaning |
|--------|-------|---------|
| `TYPING` | Green | Actively typing |
| `PAUSED` | Yellow | Simulation paused (manual) |
| `USER` | Orange | Paused - user takeover detected |
| `IDLE` | Yellow | Simulating work break |
| `STOPPED` | Red | Simulation stopped |

#### IDE Integration

When you start typing (F10 or ENTER), wrkflovv will:

1. **Create a temp file** in the same directory as the source (e.g., `.myfile_wrkflovv_tmp.py`)
2. **Open it in your IDE** (auto-detects VS Code, Cursor, Sublime, etc.)
3. **Update the file in real-time** as characters are "typed"
4. **Clean up temp files** when the file is complete or simulation stops

This lets you watch the typing happen live in your editor!

**Supported IDEs (auto-detected):**
- VS Code (`code`)
- Cursor (`cursor`)
- VSCodium (`codium`)
- Sublime Text (`subl`)
- Atom (`atom`)
- Gedit, Vim, Neovim, Nano

#### Human-Like Behavior

wrkflovv simulates realistic developer typing patterns:

**Spontaneous Speed Changes:**
- WPM varies randomly between your min/max settings
- Sometimes fast (in the zone), sometimes slow (thinking)
- No predictable patterns - completely spontaneous

**Random Pauses:**
- Micro-pauses (0.2-0.5s) - brief hesitation
- Thinking pauses (0.5-1.5s) - considering what to type
- Distraction pauses (4-10s) - checking something
- Long pauses (10-30s) - phone/drink/stretch

**Developer Habits:**
- **Ctrl+S** - Saves frequently like a real dev
- **Ctrl+Shift+I** - Auto-formats code periodically
- **Typos** - Makes realistic typos and corrects them

**Adjust WPM on the fly:**
- Press `+` to increase WPM by 5
- Press `-` to decrease WPM by 5
- Default range: 60-85 WPM (realistic developer speed)
- Settings are saved automatically!

#### Auto-Pause on User Takeover

wrkflovv detects when you take over and automatically pauses:

**Triggers:**
- Any keyboard input (except control keys)
- Mouse clicks
- Significant mouse movement
- Mouse scroll

**How it works:**
1. You're typing along...
2. You click somewhere or start typing → **AUTO-PAUSE**
3. Status changes to "USER" (orange)
4. Make your changes
5. Press `F10` to resume from exact position!

**Resume:**
- Press `F10` to continue from where it paused
- Typing resumes at the exact character position
- No need to restart the file

#### Stealth Mode (F9)

Press `F9` to toggle stealth mode, which:
- Hides the wrkflovv interface
- Shows a fake `htop`-like process list
- Typing continues in the background
- Press `F9` again to return to normal view

Perfect for when someone walks by!

---

### Headless Mode (CLI)

Run typing simulation without the TUI - perfect for scripting and automation.

```bash
wrkflovv run [OPTIONS] SOURCES...
```

#### Arguments

| Argument | Description |
|----------|-------------|
| `SOURCES` | One or more source files or directories to type from (required) |

#### Options

| Option | Default | Description |
|--------|---------|-------------|
| `--output`, `-o` | None | Output directory for typed files |
| `--min-wpm` | 20 | Minimum words per minute |
| `--max-wpm` | 70 | Maximum words per minute |
| `--no-idle` | False | Disable idle periods |
| `--loop/--no-loop` | True | Loop through files continuously |

#### Examples

**Basic usage:**
```bash
# Type a single file
wrkflovv run myfile.py

# Type multiple files
wrkflovv run file1.py file2.js file3.ts

# Type all files in a directory
wrkflovv run ./src/
```

**With options:**
```bash
# Custom WPM range (faster typing)
wrkflovv run --min-wpm 40 --max-wpm 100 ./code/

# Disable idle periods for continuous typing
wrkflovv run --no-idle ./code/

# Single pass (no looping)
wrkflovv run --no-loop ./code/

# Specify output directory
wrkflovv run -o ./output/ ./code/

# Combined options
wrkflovv run --min-wpm 30 --max-wpm 80 --no-idle --no-loop ./src/
```

**Stop the simulation:**
```
Press Ctrl+C to stop
```

**Session output:**
```
Loading source files...
Loaded 5 files
Starting typing simulation...
Press Ctrl+C to stop

Typing: main.py
Done: main.py
Typing: utils.py
Idle for 45s...
Done: utils.py

Session Stats:
  Files typed: 2
  Characters: 3,450
  Lines: 128
  Session time: 245s
```

---

## Configuration

### View Current Configuration

```bash
wrkflovv config
```

Output:
```
Configuration

Config directory: /home/user/.wrkflovv

WPM Settings:
  Min WPM: 20
  Max WPM: 70

Idle Settings:
  Min idle: 30s
  Max idle: 300s
  Idle chance: 15.0%

Typing Behavior:
  Typo chance: 2.0%
  Burst typing: True

Source Files:
  - /path/to/file1.py
  - /path/to/file2.js
```

### Configuration File

Settings are stored in `~/.wrkflovv/config.json`:

```json
{
  "min_wpm": 20,
  "max_wpm": 70,
  "min_idle": 30,
  "max_idle": 300,
  "idle_chance": 0.15,
  "typo_chance": 0.02,
  "burst_typing": true,
  "source_files": [
    "/path/to/file1.py",
    "/path/to/file2.js"
  ],
  "output_dir": ""
}
```

### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `min_wpm` | int | 60 | Minimum typing speed (words per minute) |
| `max_wpm` | int | 85 | Maximum typing speed (words per minute) |
| `min_idle` | int | 30 | Minimum idle period in seconds |
| `max_idle` | int | 300 | Maximum idle period in seconds (5 min) |
| `idle_chance` | float | 0.10 | Probability of idle period after each file (10%) |
| `typo_chance` | float | 0.015 | Probability of making a typo (1.5%) |
| `burst_typing` | bool | true | Enable variable speed bursts |
| `save_enabled` | bool | true | Ctrl+S saving behavior |
| `format_enabled` | bool | true | Auto-formatting (Ctrl+Shift+I) |
| `spontaneous_pauses` | bool | true | Random thinking pauses |
| `source_files` | list | [] | Saved source file paths |
| `output_dir` | string | "" | Default output directory |

---

## File Management

### Add Source Files

```bash
# Add a single file
wrkflovv add myfile.py

# Add multiple files
wrkflovv add file1.py file2.js file3.ts

# Add a directory (all supported files)
wrkflovv add ./src/

# Add multiple paths
wrkflovv add ./src/ ./tests/ ./lib/
```

### List Source Files

```bash
wrkflovv list-files
```

Output:
```
         Source Files
┏━━━┳━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━┓
┃ # ┃ File          ┃ Lines ┃ Chars ┃
┡━━━╇━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━┩
│ 1 │ main.py       │ 150   │ 4320  │
│ 2 │ utils.py      │ 89    │ 2150  │
│ 3 │ config.js     │ 45    │ 1200  │
└───┴───────────────┴───────┴───────┘

Total: 7,670 chars, 284 lines
```

### Clear Source Files

```bash
wrkflovv clear
```

### Supported File Types

The tool auto-detects common source code extensions:

`.py` `.js` `.ts` `.jsx` `.tsx` `.java` `.cpp` `.c` `.h` `.hpp` `.go` `.rs` `.rb` `.php` `.swift` `.kt` `.scala` `.cs` `.vue` `.svelte` `.html` `.css` `.scss` `.sass` `.less` `.json` `.yaml` `.yml` `.xml` `.md` `.txt` `.sh` `.bash` `.zsh` `.sql`

---

## CLI Reference

```
wrkflovv [OPTIONS] COMMAND [ARGS]

Commands:
  run         Run typing simulation in headless mode (no TUI)
  config      Show current configuration
  add         Add source files to configuration
  clear       Clear all source files from configuration
  list-files  List configured source files

Options:
  --version, -v  Show version and exit
  --help         Show help message and exit
```

---

## Examples

### Research Workflow

```bash
# 1. Add your research dataset
wrkflovv add ./keystroke-samples/

# 2. View loaded files
wrkflovv list-files

# 3. Run simulation (headless for data collection)
wrkflovv run --min-wpm 25 --max-wpm 55 ./keystroke-samples/

# 4. Or use interactive mode for monitoring
wrkflovv
```

### Continuous Simulation

```bash
# Run indefinitely with realistic behavior
wrkflovv run --loop ./code/
```

### Fast Typing Simulation

```bash
# Higher WPM range, no breaks
wrkflovv run --min-wpm 60 --max-wpm 120 --no-idle ./code/
```

### Single File Session

```bash
# Type one file and exit
wrkflovv run --no-loop important_file.py
```

---

## Architecture

```
wrkflovv/
├── cli.py              # CLI entry point
├── app.py              # TUI application
├── core/
│   ├── typer_engine.py # Keystroke simulation
│   ├── file_manager.py # File handling
│   └── scheduler.py    # Session management
├── ui/
│   ├── theme.py        # TUI styling
│   ├── widgets/        # Custom widgets
│   └── views/          # View components
└── utils/
    └── config.py       # Configuration management
```

---

## License

MIT License - See LICENSE file for details.

## Author

Umer Farooq Khan (umerfarooqkhan325@gmail.com)