Metadata-Version: 2.4
Name: lucky-cli
Version: 0.0.3
Summary: A lottery CLI tool built with Python for fun
License: MIT License
        
        Copyright (c) 2026 PyDeployer
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.28.1
Requires-Dist: rich>=15.0.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: typer>=0.26.7
Dynamic: license-file

# lucky-cli

A lottery CLI tool built with Python for fun. Installed command: `lucky`.

Supports Powerball (5 numbers 1–69 + special 1–26) and Mega Millions (5 numbers 1–70 + special 1–25).

## Install (dev)

```bash
uv sync
uv run lucky --help
```

## Usage

| Command | Description |
|---|---|
| `lucky pick <game> [--count N]` | Generate N valid random tickets |
| `lucky check <game> <n1..n5> --special <s>` | Check a ticket against the latest draw |
| `lucky show <game>` | Show the latest draw (date, numbers, special, jackpot) — default view |
| `lucky show <game> --history [--limit N]` | Show the last N draws |
| `lucky show <game> --stats` | Show number frequency, hot/cold numbers, odd/even distribution |
| `lucky --version` | Show the installed version |

Example:

```bash
lucky check powerball 12 18 33 44 61 --special 9
```

On every run, `lucky` checks for new draws and updates its local SQLite cache (`~/.lucky-cli/lucky.db`) before executing your command. If offline, it silently falls back to the cached data.

## Project layout

```
src/lucky/
├── cli.py            # Typer app entrypoint
├── commands/         # one module per subcommand
├── lottery/          # game rules + ticket generator
├── database/         # SQLAlchemy models/repository
├── updater/          # remote source + sync logic
└── console/          # Rich rendering helpers
tests/
```

See [CLAUDE.md](CLAUDE.md) for the full architecture spec.

## Development

```bash
uv sync              # install deps
uv run pytest        # run tests
uv run lucky <cmd>   # exercise the CLI locally
```

## Contributing

- Commits follow [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`. Use `feat!:` or a `BREAKING CHANGE:` footer for breaking changes.
- Versioning is automated from git tags (`setuptools-scm`) — never hand-edit a version string.
- Route all CLI output through `src/lucky/console/`; avoid raw `print()`.
- Add/update tests under `tests/` for any change to generator, stats, checker, or database logic.
- CI publishes to PyPI on `v*` tags via `.github/workflows/release.yml`.

## Releasing / Versioning

Version numbers are never hand-edited — they're derived from git tags via `setuptools-scm`. To cut a release:

1. Find the last release tag (skip if this is the first release):
   ```bash
   git describe --tags --abbrev=0
   ```
2. Review commits since that tag:
   ```bash
   git log <last-tag>..HEAD --oneline
   ```
3. Classify them by [Conventional Commits](https://www.conventionalcommits.org/) prefix to decide the version bump:
   - `feat:` → MINOR
   - `fix:` → PATCH
   - `feat!:` or a `BREAKING CHANGE:` footer → MAJOR
   - (first release with no prior tag: start at `v0.1.0`)
4. Add a new section to `CHANGELOG.md`, grouped by category:
   ```md
   ## v0.3.0

   ### Features
   - add stats command

   ### Fixes
   - fix check logic
   ```
5. Commit the changelog update, then create and push the tag:
   ```bash
   git add CHANGELOG.md
   git commit -m "chore: release v0.3.0"
   git tag v0.3.0
   git push origin main v0.3.0
   ```
6. Pushing the tag triggers `.github/workflows/release.yml`, which runs the test suite, builds the package, and publishes to PyPI using the `PYPI_API_TOKEN` secret — nothing else to do manually.

## Development process

This project is built with [Claude Code](https://claude.com/claude-code) using the Superpowers plugin as its development framework — brainstorming a design spec, writing an implementation plan, then executing it task-by-task with subagent-driven TDD and code review before each merge.

## License

MIT — see [LICENSE](LICENSE).
