## PR Creator

Simple workflow runner that clones target repos, applies changes via a change agent, and submits PRs.

### Use cases
- Roll out the same change across many repos (e.g., config, dependency, linting updates).
- Apply automated PRs using AI agents with optional human-written prompts.
- Re-run safely on the same repo/branch using `--change-id` to iterate on fixes.
- Drive changes from a prompt config repo for repeatable, reviewed instructions.

### Required tools
- Docker (for the cursor change agent)
- No git or GitHub CLI needed (Dulwich + GitHub API handle clone/push/PR)

### Environment variables
**Required**
- `CURSOR_API_KEY` — passed to the cursor agent.
- `GITHUB_TOKEN` — used for push and GitHub PR creation.

**Optional**
- `GIT_AUTHOR_NAME` / `GIT_AUTHOR_EMAIL` — author/committer; defaults to pr-creator placeholders if unset.
- `LOG_LEVEL` — logging level; default `INFO`.
- `CHANGE_AGENT` — choose change agent; default `cursor`.
- `EVALUATE_AGENT` — choose evaluate agent; default `cursor`.
- `NAMING_AGENT` — choose naming agent; default `cursor`.
- `CURSOR_IMAGE` — docker image for cursor agent; default `leonpatmore2/cursor-agent:latest`.
- `CURSOR_MODEL` — cursor model to use; default `gpt-5.2`.
- `CURSOR_ENV_KEYS` — comma-separated env keys forwarded to the agent; default `CURSOR_API_KEY`.
- `DATADOG_API_KEY` / `DATADOG_APP_KEY` — required if using Datadog repo discovery.
- `SUBMIT_CHANGE` — submitter; default `github`.
- `SUBMIT_PR_BASE` — target base branch; default repo default.
- `SUBMIT_PR_BODY` — PR body; default `Automated changes generated by pr-creator.`
- `DEFAULT_BRANCH_PREFIX` — branch name prefix used when no change_id is provided; default `auto/pr`.
- `GITHUB_DEFAULT_ORG` — default GitHub org/owner to prepend when repo args are provided without an owner (e.g., `--repo my-repo` -> `github.com/<org>/my-repo.git`).

### Commands
- `pipenv run python -m pr_creator.cli --prompt "<prompt>" --relevance-prompt "<relevance>" --repo <repo_url> --working-dir .repos`
- `make test-e2e` — run the e2e pytest (requires env vars set).
- `make lint` — flake8.
- `make format` — black (requires Python ≥3.12.6).

### CLI arguments
**Prompts**
- `--prompt` — main prompt text. Required unless using prompt config.
- `--relevance-prompt` — relevance filter prompt. Required unless using prompt config.

**Prompt config (alternative to passing prompts directly)**
- `--prompt-config-owner` — GitHub owner of the prompt config repo. Must be set with `--prompt-config-repo` and `--prompt-config-path`.
- `--prompt-config-repo` — GitHub repo name containing the prompt config file.
- `--prompt-config-ref` — git ref for the prompt config file; default `main`.
- `--prompt-config-path` — path to the YAML prompt config file inside the repo.

**Change ID (for static branches)**
- `--change-id` — Change ID to use for static branch names. When provided, ensures re-runs use the same branch name (format: `{branch_prefix}-{change_id}`). Can also be set in prompt config YAML (takes precedence over CLI arg).

**Repositories**
- `--repo` — repository URL to process. Can be passed multiple times; required if not using Datadog discovery.

**Datadog discovery**
- `--datadog-team` — Datadog team name to discover repos (requires `DATADOG_API_KEY` and `DATADOG_APP_KEY`).
- `--datadog-site` — Datadog API base URL; default `https://api.datadoghq.com`.

**Runtime**
- `--working-dir` — where repos are cloned; default `.repos`.
- `--log-level` — logging level; default `INFO`.

### Workspace management
- Workspaces live under `--working-dir` (default `.repos`); directories are auto-created per repo.
- When `--change-id` is set, the workspace path is deterministic (`<repo>-<change_id>`) and reused across runs so the same branch can be reapplied.
- Without `--change-id`, a fresh workspace with a random suffix is created and cleaned up after each repo finishes.
- To start fresh, remove the working directory (e.g., `rm -rf .repos`).

### Example (Docker)

```sh
docker run --rm \
  -e CURSOR_API_KEY \
  -e GITHUB_TOKEN \
  leonpatmore2/pr-creator:latest \
  --prompt-config-owner LeonPatmore \
  --prompt-config-repo pr-creator \
  --prompt-config-ref main \
  --prompt-config-path examples/prompt-config.yaml \
  --repo https://github.com/LeonPatmore/cheap-ai-agents-aws \
  --working-dir /tmp/repos \
  --log-level INFO
```
