Metadata-Version: 2.4
Name: RideSims
Version: 0.3.0
Summary: For running automated ride sequences for RideSims.
Author-email: copev313 <copev313@gmail.com>
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: keyboard>=0.13.5
Requires-Dist: pydirectinput>=1.0.4
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.27.1
Dynamic: license-file

# RideSims

RideSims is a Python CLI package for running automated ride operation sequences
for RideSims simulations.

## Requirements

- Python 3.13+
- uv (Python/dependency manager)
- A local environment where keyboard and mouse automation is allowed

## Installation

Create or update the environment and install project dependencies:

```bash
uv sync
```

Install with development tools:

```bash
uv sync --group dev
```

## Running The CLI

Run RideSims with uv-managed execution:

```bash
uv run ridesims list-rides
uv run ridesims validate-rides
uv run ridesims run-automated velocicoaster
uv run ridesims run-automated velocicoaster --max-cycles 5
uv run ridesims run-automated velocicoaster --run-once
uv run ridesims run-automated velocicoaster --max-duration-seconds 120
uv run ridesims run-automated velocicoaster --dry-run
uv run ridesims run-automated velocicoaster --backend keyboard --verbose --no-color
uv run ridesims run-automated velocicoaster --no-strict-preflight
uv run ridesims run-automated velocicoaster --strict-backend-probe
uv run ridesims run-automated velocicoaster --config ./ridesims.toml
uv run ridesims run-automated velocicoaster --json-logs
```

If no ride name is provided for `run-automated`, the CLI prompts for one.

## Available Commands

- `list-rides`: Show all supported rides.
- `validate-rides`: Validate ride imports and `run()` contract checks.
- `run-automated <ride_slug>`: Start the automation sequence for a ride.

`run-automated` expects a ride slug (for example `velocicoaster`).

Key `run-automated` options:

- `--max-cycles <n>`: stop after N cycles.
- `--run-once`: shorthand for running exactly one cycle.
- `--max-duration-seconds <seconds>`: stop after a time limit.
- `--dry-run`: simulate operations without keyboard input.
- `--backend <auto|keyboard|pydirectinput>`: choose input backend.
- `--strict-backend-probe`: fail if runtime capability probing reports backend issues.
- `--strict-preflight` / `--no-strict-preflight`: control preflight failure policy.
- `--verbose`: enable verbose logging.
- `--no-color`: disable colored terminal output.
- `--config <path>`: load defaults from a TOML file.
- `--json-logs`: output machine-readable JSON logs.

Feature-flag based behavior can be configured in `[features]`:

- `event_stream = true`: emits structured lifecycle events (including correlation IDs) during runs.
- `extended_backend_probe = true`: reserved toggle for progressively deeper backend probes.

If `--config` is not provided, RideSims checks these paths in order:

- `./ridesims.toml`
- `./.ridesims.toml`

Example config:

```toml
[run]
backend = "auto"
strict_backend_probe = true

[features]
event_stream = true
extended_backend_probe = false
```

## Ride Guides

Each ride has setup and operation notes:

- [Everest](ridesims/rides/Everest/README.md)
- [Splash Mountain](ridesims/rides/SplashMountain/README.md)
- [River Adventure](ridesims/rides/RiverAdventure/README.md)
- [Velocicoaster](ridesims/rides/Velocicoaster/README.md)
- [Maverick](ridesims/rides/Maverick/README.md)
- [IceBreaker](ridesims/rides/IceBreaker/README.md)

## Architecture Layers

- `ridesims/cli.py`: command registration, argument parsing, user-facing output.
- `ridesims/core/session.py`: run session option assembly and run-bound warnings.
- `ridesims/core/runtime.py`: bounded cycle/time execution loop.
- `ridesims/core/errors.py`: typed errors and centralized command exit policy map.
- `ridesims/backends/`: backend resolution and runtime capability probing.
- `ridesims/rides/`: ride modules plus the registry and preflight checks.
- `ridesims/config.py`: typed TOML defaults and override loading.

## Exit Code Policy

Shell-friendly process exit codes are standardized across commands.

- `list-rides`
	- `0`: command completed successfully.
- `validate-rides`
	- `0`: all registered rides validated successfully.
	- `1`: one or more ride preflight checks failed.
- `run-automated`
	- `0`: ride automation completed successfully.
	- `1`: user/config/preflight/backend/ride contract error prevented run.
	- `130`: interrupted by user (`Ctrl+C`).

## Development

Lint the project:

```bash
uv run ruff check .
```

Format imports:

```bash
uv run isort .
```

Validate release metadata locally:

```bash
uv run python scripts/validate_release.py v0.1.0
```

Run tests:

```bash
uv run python -m pytest -q
```

### Continuous Integration

The CI workflow runs Ruff and the unit test suite for pushes to the `test`
branch and pull requests whose target branch is `test`. Run the same checks
locally before opening a pull request:

```bash
uv run ruff check .
uv run python -m pytest -q
```

### Creating a Release

Before creating the first PyPI release, configure GitHub Environment `pypi`
and a PyPI Trusted Publisher for GitHub owner `copev313`, repository
`RideSims`, workflow `release.yml`, and environment `pypi`. This uses GitHub
OIDC, so no PyPI API token secret is required.

For each release:

1. Set `project.version` in `pyproject.toml` to `X.Y.Z`.
2. Add a `## [X.Y.Z]` section to `CHANGELOG.md`.
3. Commit the release changes and create a matching annotated tag:

   ```bash
   git tag -a vX.Y.Z -m vX.Y.Z
   git push origin vX.Y.Z
   ```

The tag must match `vMAJOR.MINOR.PATCH`. The release workflow validates the
tag, version, and changelog; runs lint and tests; builds the distribution;
publishes it to PyPI; and then creates the GitHub release. Manual release
workflow runs validate a proposed tag only and do not publish.

Release/versioning policy:

- [Release Policy](docs/release-policy.md)
