Metadata-Version: 2.4
Name: github-issue-fixer
Version: 0.0.1
Summary: Cache assigned GitHub issues and prepare manual Codex commands.
Author: Kaizten Analytics
License-Expression: LicenseRef-Proprietary
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# GitHub Issue Fixer

`github-issue-fixer.py` caches GitHub issues assigned to the authenticated GitHub CLI user and prepares manual Codex commands to solve them locally.

The script opens Warp best-effort, but it never runs Codex automatically. For each selected issue it writes a prompt file under the cache directory and prints the exact `codex` command to paste/run in Warp when ready.

## Requirements

- Python 3.10 or newer
- GitHub CLI (`gh`)
- An authenticated GitHub CLI session:

```bash
gh auth login
```

- Warp terminal (`warp-terminal`) for fix commands
- Local clones of target repositories under your home directory by default

## Usage

```bash
./github-issue-fixer.py --refresh
./github-issue-fixer.py --list
./github-issue-fixer.py --org ORGANIZATION --refresh
./github-issue-fixer.py --repo OWNER/REPO --list
./github-issue-fixer.py --repo OWNER/REPO --issue 123 --fix
./github-issue-fixer.py --repo OWNER/REPO --fix
./github-issue-fixer.py --org ORGANIZATION --fix
```

By default, the analyzed username is the authenticated `gh` user. Use `--username` to inspect issues assigned to another GitHub user while still using the logged-in `gh` account for organization and repository access:

```bash
./github-issue-fixer.py --username monalisa --refresh
./github-issue-fixer.py --username monalisa --list
./github-issue-fixer.py --username monalisa --repo OWNER/REPO --fix
```

Use `--cache-dir` to change local cache storage:

```bash
./github-issue-fixer.py --cache-dir ~/tmp/github-issue-fixer --refresh
```

Use `--repos-root` when clones are not under `~`:

```bash
./github-issue-fixer.py --repos-root ~/work --repo OWNER/REPO --issue 123 --fix
```

## Commands

### `--refresh`

Reads the authenticated GitHub username with `gh`, discovers organizations with access, lists non-archived repositories in each organization, and caches open non-PR issues assigned to the selected username. It prints the authenticated GitHub user, the username under analysis, the per-user cache directory, organization discovery, and per-repository issue analysis progress.

Use `--org ORGANIZATION` to refresh one organization, or `--repo OWNER/REPO` to
refresh one repository.

### `--list`

Prints cached open assigned issues:

```text
| Repository | Issue number | Issue title | Issue URL | Time since creation |
```

Issue titles are normalized to one line and limited to 30 characters.

Run `--refresh` first when you want current GitHub data.

Use `--org ORGANIZATION` to list one cached organization, or `--repo OWNER/REPO`
to list one cached repository.

### `--repo OWNER/REPO --issue NUMBER --fix`

Finds the matching local clone by comparing GitHub `origin` remotes under `--repos-root`, fetches the latest issue details, opens Warp if it is not already running, writes a prompt file, and prints a manual Codex command.

The issue number may also be written as `#123`, but quote or escape it in a shell because `#` starts a comment.

### `--repo OWNER/REPO --fix`

Prepares one manual Codex command for each cached open assigned issue in the repository.

### `--org ORGANIZATION --fix`

For each cached repository in the organization, selects the oldest cached open assigned issue and prepares one manual Codex command.

## Local Storage

By default, files are stored under:

```text
~/.github-issue-fixer/
  USERNAME/
    ORGANIZATION/
      issues.json
      prompts/
        REPO/
          issue-NUMBER.md
```

Each analyzed username has its own cache directory, and each organization under that username has its own `issues.json`. Prompt files contain issue details and are safe to regenerate.

## Notes

- Pull requests are excluded.
- Archived repositories are skipped.
- GitHub search can return at most 1000 assigned issues per repository.
- Warp command prefill is not used; the script prints commands for manual execution so Codex does not start solving until you run the command.
