# Contributing to wheriflo

Thanks for your interest in contributing! Here's how to get started.

## Development Setup

```bash
git clone https://github.com/harrisonhoffman1/wheriflo.git
cd wheriflo
pip install -e ".[dev]"
```

## Running Tests

```bash
python -m pytest tests/ -v
```

Tests cover the compiler, packager, validator, engine, CLI, sandbox, and iOS compatibility.

## Project Structure

```
src/wheriflo/
├── cli.py              # CLI entry point
├── compiler.py         # Lua 5.1 compile + bytecode conversion
├── packager.py         # GWC/GWZ packaging + metadata extraction
├── validator.py        # GWC binary validation
├── mcp_server.py       # MCP server (FastMCP)
├── runtime/
│   ├── engine.py       # Sandboxed Lua executor
│   ├── web_server.py   # Browser play-test server
│   └── wherigo_shim.lua  # Lua-side Wherigo API
└── resources/
    ├── api_reference.md   # Lua API docs
    ├── design_guide.md    # Design best practices
    ├── starter.lua        # Template for `init`
    └── web_player.html    # Browser UI
```

## Making Changes

1. Create a branch from `main`
2. Make your changes
3. Add or update tests as needed
4. Run `python -m pytest tests/ -v` — all tests must pass
5. Open a pull request

## Code Style

- Follow existing patterns in the codebase
- Keep functions focused and small
- Add docstrings to public functions
- No type stubs needed — use inline type hints

## Key Rules for Wherigo Cartridges

If you're adding features that generate or modify Lua code:

- **Never set `Media = nil` or `Icon = nil`** — crashes the iOS app
- **Use `ShowObjects = "OnEnter"`** not `"OnEntry"`
- **No apostrophes in Lua comments** — crashes the Groundspeak compiler
- **Keep functions under ~4KB** — Groundspeak compiler limit
- **Output pure ASCII** — use Lua escapes for non-ASCII characters

## Reporting Bugs

Open an issue at https://github.com/harrisonhoffman1/wheriflo/issues with:
- What you expected to happen
- What actually happened
- Steps to reproduce
- Your Python version and OS
