Development Guide
Documentation
Before writing documentation, identify the targeted readers for each section, what that section
should provide to them, and the writing principles that follow from that purpose. For example,
Usage in the README is for end users installing and running the tool, so keep release
verification, debugging, and maintainer-only commands out of it.
Environment
Set up the development environment:
uv sync --prerelease=allow
Prompt Diary requires the published openai-codex Python SDK. The current SDK packaging uses
prerelease packages, so local dependency resolution needs --prerelease=allow. Prompt Diary starts
the SDK against the local codex CLI found on PATH, so live tests reuse the same Codex
authentication as the CLI.
The repository also includes an optional Ubuntu 24.04 devcontainer. It builds from
.devcontainer/Dockerfile, installs the project with uv sync --locked --python 3.10, and includes
the Codex and Claude Code CLIs. See the devcontainer notes for
container layout, persistent volumes, and authentication notes.
Run the CLI from the project environment:
uv run report --help
Developer workflow commands that are intentionally not highlighted in the README Usage section:
uv run report prepare --date YYYY-MM-DD --timezone Area/City
uv run report generate render --date YYYY-MM-DD --timezone Area/City
Standalone generation phase commands are covered in the Generation Pipeline Framework.
Install the local checkout as an isolated uv tool:
uv tool install --prerelease=allow .
Dependencies
Add runtime dependencies with:
uv add <package>
Add development-only dependencies with:
uv add --dev <package>
Build And Release
Build source and wheel distributions:
uv build
Publish release artifacts only after the package metadata and target registry are configured:
uv publish
Type Checking
Type checking uses basedpyright.
The project config enables strict mode for src and tests. Add type annotations by best effort
for new and changed code. This is a hard rule: prefer explicit, checkable types whenever they
improve clarity or allow basedpyright to verify behavior.
Use accurate types when possible instead of relying on repeated validation. At module boundaries,
parse untrusted or loosely structured inputs into precise internal types, then pass those types
through the rest of the code. Do not validate a value and then continue passing the original
loose representation when a richer type, dataclass, TypedDict, NewType, enum, or other
structured representation can preserve the invariant for callers and the type checker.
uv run basedpyright
Tests
Tests use pytest. The pytest config lives in pyproject.toml and uses
strict config and marker validation.
uv run pytest
Codex/MCP integration tests are opt-in because they may spend model tokens and require Codex
authentication. Run opt-in tests with the --run-codex-mcp flag. Pass it to the full suite or to a
specific file:
uv run pytest --run-codex-mcp
uv run pytest tests/integrations/test_codex_mcp_integration.py --run-codex-mcp
uv run pytest tests/integrations/test_evidence_extraction_codex.py --run-codex-mcp
Coverage
Coverage uses coverage.py and is configured to require 100% line coverage for package code. Default coverage uses mocked Codex runner tests; the real Codex agent wrapper test remains opt-in because it may spend model tokens.
uv run coverage run -m pytest
uv run coverage report
Linting And Formatting
Linting and formatting use ruff. Ruff is configured for Python 3.10. The lint rule set is explicit and intentionally broader than Ruff’s defaults, covering imports, modernization, bug-prone patterns, datetime safety, security checks, pathlib usage, pytest style, exception handling, and simplification rules.
uv run ruff check
uv run ruff format --check
uv run ruff format
Pre-Submit Checks
Before submitting changes, run:
uv run ruff check
uv run ruff format --check
uv run basedpyright
uv run pytest
uv run coverage run -m pytest
uv run coverage report
uv build