Metadata-Version: 2.4
Name: ghost-typer
Version: 0.1.0
Summary: A minimalist CLI for creating aesthetic code typing animations. Perfect for sharing code demos on social media with a clean, terminal-first look.
Author: 
Keywords: terminal,demo,typing,rich,pygments
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: colorama>=0.4.6
Requires-Dist: Pygments>=2.20.0
Requires-Dist: questionary>=2.1.1
Requires-Dist: rich>=15.0.0
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: twine>=5.1.1; extra == "dev"

Ghost-Typer is a terminal demo tool that replays source code as if someone were typing it live. It is designed for polished screen recordings, short-form demos, and social media clips.

## What it does

- Reads a source file and detects the language when possible.
- Replays the file character by character with human-like typing delays.
- Supports syntax highlighting with Rich and Pygments.
- Supports built-in Pygments themes and custom JSON themes.
- Detects special pause comments such as `pause: 2s` to add dramatic pauses.
- Offers both a classic command-line mode and an interactive setup wizard.

## Requirements

- Python 3.13 or newer is recommended.
- A virtual environment is strongly recommended.

## Install from a clone

```bash
git clone <repo-url>
cd ghost-typer
python -m venv venv
```

### Windows PowerShell

```powershell
.\venv\Scripts\Activate.ps1
pip install rich pygments colorama questionary
```

### macOS / Linux

```bash
source venv/bin/activate
pip install rich pygments colorama questionary
```

If you prefer, you can also install the packages globally, but a virtual environment is the safest option.

## Install from PyPI

When the package is published, install it with:

```bash
pip install ghost-typer
```

Run it from anywhere with:

```bash
ghost-typer --cli
```

## Quick start

### Interactive mode

The interactive wizard opens automatically when you run the tool with no extra CLI flags, or explicitly with `--cli`.

```bash
python ghost_typer.py
```

or

```bash
python ghost_typer.py --cli
```

If you start it with only a source file, it will also enter the interactive flow without asking for the file again:

```bash
python ghost_typer.py script.py
```

### Classic CLI mode

If you pass additional options, Ghost-Typer uses the standard CLI flow.

```bash
python ghost_typer.py script.py --theme pygments:dracula --speed 1.2
```

## How it works

Ghost-Typer can be used in two ways:

### 1. Interactive wizard

<video src="https://github.com/user-attachments/assets/4448cab2-5c91-4f40-80c5-a6f429f84f2d" autoplay loop muted playsinline width="100%"></video>

The wizard guides you through:

- choosing a theme
- choosing a lexer if needed
- configuring typing speed
- configuring delay ranges
- confirming whether to clear the screen before starting

This mode is designed to feel like a clean setup dashboard.

### 2. Direct command-line configuration

You can still pass parameters directly from the terminal for faster workflows, scripts, or automation.

## Themes

Ghost-Typer supports two theme sources:

### Built-in Pygments themes

Use the `pygments:` prefix:

```bash
python ghost_typer.py script.py --theme pygments:monokai
python ghost_typer.py script.py --theme pygments:dracula
```

### Custom JSON themes

You can load a theme from a local JSON file or from a theme file inside the `themes/` folder.

Examples:

```bash
python ghost_typer.py script.py --theme themes/Clancy\ Stealth.json
python ghost_typer.py script.py --theme themes/example-neon.json
python ghost_typer.py script.py --theme monokai
```

If the JSON theme lives inside `themes/`, you can use its name without the extension:

```bash
python ghost_typer.py script.py --theme example-neon
```

### Theme catalog

List available built-in and local themes with:

```bash
python ghost_typer.py --list-themes
```

## Custom theme format

A custom theme JSON can define:

- `metadata`
- `terminal`
- `syntax`
- `ui`
- `typing_config`

Example:

```json
{
  "metadata": {
    "name": "Clancy Stealth",
    "author": "JoseDev",
    "version": "1.0"
  },
  "terminal": {
    "background": "#000000",
    "cursor_color": "#FFE700",
    "cursor_style": "block"
  },
  "syntax": {
    "keyword": "#FF0000",
    "string": "#FFE700",
    "function": "#FFFFFF"
  },
  "ui": {
    "header_color": "#FFE700",
    "border_color": "#FF0000"
  },
  "typing_config": {
    "base_speed": 0.05,
    "variance": 0.02,
    "line_pause_multiplier": 1.5
  }
}
```

## Pause comments

Ghost-Typer can pause on special annotations inside the file:

```python
# pause: 2s
```

Supported units:

- `ms`
- `s`
- `m`

## CLI options

### Core options

- `file`: source file to replay
- `--theme`: theme name, built-in Pygments theme, or JSON path
- `--themes-dir`: folder used to search local JSON themes
- `--list-themes`: print available themes and exit
- `--cli`: open the interactive wizard
- `--language`: force a lexer alias
- `--no-clear`: do not clear the screen before starting

### Typing options

- `--min-delay`: minimum delay per character in milliseconds
- `--max-delay`: maximum delay per character in milliseconds
- `--speed`: speed multiplier
- `--newline-multiplier`: extra multiplier for newline pauses

### Other options

- `--cursor`: visible cursor symbol in non-interactive mode

## Examples

### Replay a Python file with a built-in theme

```bash
python ghost_typer.py script.py --theme pygments:dracula
```

### Replay a file using a local theme JSON

```bash
python ghost_typer.py script.py --theme themes/Clancy\ Stealth.json
```

### Open the interactive wizard

```bash
python ghost_typer.py --cli
```

### Use a custom lexer and speed settings

```bash
python ghost_typer.py script.py --language python --min-delay 20 --max-delay 90 --speed 1.4
```

## Notes

- The tool respects the terminal's native background in the minimalist UI mode.
- If you pass additional CLI arguments, Ghost-Typer uses the command-line flow instead of the simplified interactive path.
- Custom themes inside `themes/` are discovered automatically by name.

## Project structure

```text
ghost-typer/
├── ghost_typer.py
├── pyproject.toml
├── MANIFEST.in
├── themes/
│   ├── Clancy Stealth.json
│   ├── dracula.json
│   ├── example-neon.json
│   └── monokai.json
└── venv/
```

## Packaging and publishing (PyPI)

### 1. Update version

Before each release, bump the version in `pyproject.toml`.

### 2. Build distribution artifacts

From the project root:

```bash
python -m pip install --upgrade build twine
python -m build
```

This generates:

- `dist/*.tar.gz` (source distribution)
- `dist/*.whl` (wheel)

### 3. Validate package metadata

```bash
python -m twine check dist/*
```

### 4. Upload to TestPyPI (recommended)

```bash
python -m twine upload --repository testpypi dist/*
```

Test install from TestPyPI:

```bash
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple ghost-typer
```

### 5. Upload to PyPI

```bash
python -m twine upload dist/*
```

If you use an API token, set it as the password in Twine with username `__token__`.

## License

Add your preferred license here.
