pysleigh 0.1.9a5
Modular CLI helpers for Advent of Code workflows.
Requires Python: >=3.12

# PySleigh

`pysleigh` is a Typer-driven CLI assistant for Advent of Code. It keeps all IO, scaffolding, runs, and submissions beside your solutions and gives you dry-run previews before any change lands on disk or on the AoC website.

## How the CLI behaves
- Every command runs in a clear scope: you point it at a project root and a year/day, then ask it to fetch input, fetch the article, run or test a solution, submit an answer, or scaffold files.
- Actions follow the “scope → action → artifact” pattern: they operate on one concern, do a single thing, and report the created or updated artifact (inputs, articles, answers, solution templates).
- Dry-run flags (`--dry-run`) appear on each command so you can observe what would change without touching your repo or the Advent of Code site.
- Helper modules (`paths`, `context`, `loader`, `session`) stay outside the CLI decorators so the commands remain declarative and easier to script or test.

## Key commands
- `pysleigh data fetch-input <year> <day>` downloads the day’s input (supports `--overwrite`, `--dry-run`).
- `pysleigh data fetch-article <year> <day>` saves the article HTML plus a title line so scaffolding knows the correct header.
- `pysleigh data refresh-answers <year> <day>` reruns your solution, rewrites `answers/year_{n}/answer_{n}_day_{d}.txt`, or dry-runs the write.
- `pysleigh solution run|test|submit` executes, validates, or submits your solution; they log each step, honor dry-run, and explain success/failure details.
- `pysleigh solution scaffold <year> <day>` bootstraps a template under `solutions/year_{n}/solution_{n}_day_{d}.py` using the guessed title. `pysleigh solution prepare` batches input/article fetch plus scaffold with optional overwrites.
- `pysleigh verify answers <year> <day>` checks your outputs against cached answers (optional `--part`), prints timings, and records status/timing metadata in `answers/year_{n}/metadata_year_{n}.json` (toggle with `--metadata/--no-metadata`). Metadata is grouped as `{ "<year>": { "DD": {...} } }` with boolean statuses and timings in milliseconds to keep merges sane.
- `pysleigh version` prints the installed PySleigh version (read dynamically from package metadata or your local `pyproject.toml` when running editable installs).

## Installation & invocation
- Install straight from PyPI (`pip install pysleigh`) or, for hacking on the CLI, use `pip install -e .`.
- Run `pysleigh` directly once it’s on your PATH, or wrap it in `uv` (`uv run pysleigh -- solution run 2023 1`) to isolate dependencies and leverage tooling helpers.
- Use `--project-root /path/to/advent-of-code-python` (or `PYSLEIGH_PROJECT_ROOT=/path`) when invoking the CLI from outside your AoC repo so the built-in `PathConfig` can resolve inputs, answers, and article directories. The CLI will echo when it switches project roots for a subcommand so you can confirm which tree it is mutating.

## Configuration
- `PathConfig` expects the usual layout (`inputs/year_{n}/input_{n}_day_{d}.txt`, `articles/year_{n}/article_{n}_day_{d}.md`, `answers/year_{n}/answer_{n}_day_{d}.txt`, `solutions/year_{n}/solution_{n}_day_{d}.py`). Commands will create missing parent directories automatically.
- Set `SESSION_TOKEN` before running networked commands:
  ```bash
  export SESSION_TOKEN="$(security find-generic-password -s adventofcode -w)"
  ```
  Any secure credential store (`security`, `pass`, `keyring`, etc.) works; combine it with `direnv`, `dotenv`, or `uv` secrets so the token never appears in source control. PySleigh reports a clear error if the variable is missing or empty.
- Dry-run flags on every command let you confirm submit candidates, file writes, and fetches before touching the file system or AoC.

## Development & testing
- `pytest --cov=src --cov-report=term-missing` runs the suite; tests mirror the CLI modules so behavior stays aligned with production commands.
- Lint via `ruff check .` and type-check with `ty check` (configured in `pyproject.toml`), keeping 100-char lines and Python 3.12 typing idioms.
- Mutation testing via `mutmut run` is recommended after behavior changes—the existing suite already kills every mutant in commands/loaders/session helpers.