106 lines
4.2 KiB
Markdown
106 lines
4.2 KiB
Markdown
# Gotcha
|
|
|
|
Gotcha is a lightweight Gitea client with a reusable Rust core, a CLI, and a
|
|
native iOS application. The iOS interface is UIKit/Swift; UniFFI exposes the
|
|
Rust application logic to Swift.
|
|
|
|
On the icon: git in a tea cup. it is obvious, isn't it?
|
|
|
|
On the name: well, tea, we established that. there is something tea like called
|
|
matcha. and this is git. so gotcha, because gitcha sounds dumb. Stop rolling
|
|
your eyes.
|
|
|
|
In general, this app is mainly meant for self-hosters who run their own small
|
|
installation of gitea and want to pay attention to what their AI agents push to
|
|
their projects. decentralisation is the game, so this is for that use case. this is
|
|
not necessarily the app to use when you manage or frequent a large instance.
|
|
|
|
## 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`: Rust application core and UniFFI API used by iOS
|
|
- `ios`: native UIKit application for activity, repositories, favorites,
|
|
issues, milestones, pull requests, commit history, changed files, and diffs; 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
|
|
|
|
Build the workspace with `cargo build`; the CLI executable is written to
|
|
`target/debug/gotcha`. To build only the CLI, use `cargo build -p gotcha-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 -- issue list --milestones "Version 1.0" --state open
|
|
cargo run -p gotcha-cli -- issue show 7
|
|
cargo run -p gotcha-cli -- issue close 7
|
|
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.
|
|
|
|
## Architecture
|
|
|
|
`gotcha_gitea` owns Gitea access, authentication, validation, mutations, and
|
|
relationships between Gitea objects. The CLI is a terminal presentation layer:
|
|
it parses arguments and YAML, invokes shared client operations, and formats the
|
|
results. `gotcha-app` owns application state, preferences, favorites,
|
|
Keychain-backed credentials, and view-ready UniFFI records. UIKit owns native
|
|
navigation, controls, layout, and other platform presentation behavior.
|
|
|
|
New Gitea workflows belong in `gotcha_gitea::Client` first, then receive CLI or
|
|
app presentation as needed. Future work includes iOS integrations such as
|
|
sharing, notifications, and background refresh.
|
|
|
|
## iOS app
|
|
|
|
Server tokens are kept in the Apple Keychain; JSON preferences contain only
|
|
server metadata, settings, 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`.
|
|
|
|
See [TESTING.md](TESTING.md) for the complete build, simulator, gesture, and
|
|
release regression checklist.
|