# Gitea Tools

A collection of Python and Bash scripts to automate interactions with Gitea instances.

## Supported Instances

| Remote         | Host                       | Org / Repo                          |
|----------------|----------------------------|-------------------------------------|
| `dadeschools`  | `gitea.dadeschools.net`    | `Contractor / Timesheet`            |
| `prgs`         | `gitea.prgs.cc`            | `Scaled-Tech-Consulting / Timesheet`|

## Authentication

Scripts extract credentials from the macOS keychain automatically — no tokens on the command line.

- **dadeschools** — HTTPS via `git credential fill` (SSH:2222 is flaky)
- **prgs** — SSH via `ssh://git@gitea-ssh.prgs.cc:2222` (SSH is reliable here)

Ensure you've logged in via Git over HTTPS at least once so the keychain caches your credentials.

## Available Scripts

| Script              | Description                                                        |
|---------------------|--------------------------------------------------------------------|
| `create_issue.py`   | Create an issue (`--remote`, `--title`, `--body`, `--body-file`)   |
| `create_pr.py`      | Open a Pull Request (`--remote`, `--title`, `--head`, `--base`)    |
| `close_issue.sh`    | Close a specific issue (dadeschools only)                          |
| `mark_issue.sh`     | Claim/release an issue via `status:in-progress` label              |
| `manage_labels.py`  | Create label set and apply label mappings (`--dry` to preview)     |
| `mirror_refs.sh`    | Mirror branches + tags between dadeschools ⇄ prgs                  |

### Quick Examples

```bash
# Create an issue
./create_issue.py --title "Fix PDF output" --body "Blank on Safari"

# Create an issue on the prgs instance
./create_issue.py --remote prgs --title "Add tests" --body-file description.md

# Create a PR
./create_pr.py --title "feat: add validation" --head feat/validation --body "Closes #12"

# Close issue #5
./close_issue.sh 5

# Claim an issue before working on it
./mark_issue.sh 10 start

# Release when done
./mark_issue.sh 10 done

# Mirror refs (dry-run by default)
./mirror_refs.sh

# Actually push the refs
./mirror_refs.sh --apply
```

Use `--help` on any Python script or shell script for full usage details.

## Mirror Refs

`mirror_refs.sh` keeps branches and tags in sync between dadeschools and prgs:

- **Additive only** — never deletes branches or tags
- **Dry-run by default** — pass `--apply` to actually push
- **Divergence protection** — shared branches that have diverged are skipped with a warning; pass `--force` to override
- Uses a bare repo cache in `/tmp/gitea-mirror-Timesheet` for isolation
- Won't auto-close or merge anything — just ref mirroring

## Tests

Run the full test suite:

```bash
python3 -m pytest tests/ -v
```

| Test file                | Covers                                                  |
|--------------------------|---------------------------------------------------------|
| `test_create_issue.py`   | Arg parsing, remote resolution, payload, auth, errors   |
| `test_create_pr.py`      | Arg parsing, remote resolution, payload, auth, errors   |
| `test_credentials.py`    | `get_credentials()` parsing edge cases                  |
| `test_manage_labels.py`  | Label create/skip, dry run, mapping, constant validation|
| `test_shell_scripts.py`  | `close_issue.sh` + `mark_issue.sh` arg validation       |
| `test_mirror_refs.py`    | Flags, safety defaults, local integration tests         |

All tests mock network and keychain access — no real API calls are made.