# Gotcha

Gotcha is a lightweight Gitea client built in Rust. Development starts with a
reusable API crate and a CLI test bed; the same crate will back the Slint iOS
application.

## Workspace

- `gotcha_gitea`: reusable asynchronous Gitea API client with the complete
  typed Gitea 1.25 API and model surface
- `gotcha`: CLI for typed common operations and arbitrary API requests
- `gotcha-app`: Slint iOS client for servers, owned repositories, favorites,
  open issues, and issue details; bundle identifier `de.rfc1437.gotcha`

The generated API modules and models cover every Gitea 1.25 operation. The
low-level request API remains available for newer instance-specific endpoints;
purpose-built CLI and app views are added feature-by-feature.

See [API_COVERAGE.md](API_COVERAGE.md) for the live contract inventory and the
separate API-crate and CLI coverage status.

## CLI

Store each server profile in `~/.config/gotcha/config`:

```sh
cargo run -p gotcha-cli -- auth login gitea.example.com

cargo run -p gotcha-cli -- server version
cargo run -p gotcha-cli -- user show
cargo run -p gotcha-cli -- repo list
cargo run -p gotcha-cli -- repo show
cargo run -p gotcha-cli -- issue list
cargo run -p gotcha-cli -- milestone list
cargo run -p gotcha-cli -- pull list
cargo run -p gotcha-cli -- api request GET repos/owner/project/issues
cargo run -p gotcha-cli -- api request POST user/repos '{"name":"demo"}'
```

`auth login` derives `https://gitea.example.com` from the server name and reads
the token from standard input with echo disabled. The resulting plain YAML file
at `~/.config/gotcha/config` has mode `0600` and one entry per server:

```yaml
servers:
  gitea.example.com:
    url: https://gitea.example.com
    token: your-token
```

Inside a Git repository, Gotcha matches its remotes to these server URLs and
derives the `owner/repository` scope. Use `--server gitea.example.com` when selection is
ambiguous, or `--url`/`GITEA_URL` for an unconfigured server. Tokens are never
accepted as command-line arguments or environment variables.

## Direction

1. Exercise and type API areas in the CLI: repositories, issues and pull
   requests, Actions, notifications, organizations, packages, administration.
2. Add the Slint shell and move proven read workflows into touch-first screens.
3. Add write workflows and iOS integrations such as sharing, notifications,
   and background refresh.

## iOS app

Server tokens are kept in the Apple Keychain; the JSON preferences contain only
server metadata and favorites. The app requires Xcode, XcodeGen, an installed
iOS Simulator runtime, and Rust's
`aarch64-apple-ios` and `aarch64-apple-ios-sim` targets. Generate the project
after installing those prerequisites:

```sh
cd ios
xcodegen generate
open Gotcha.xcodeproj
```

For a fast host-side check, run `cargo test -p gotcha-app`.