initial commit

README.md

@@ -0,0 +1,61 @@
+# 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
+- iOS/Slint app: next crate, 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 secure token storage,
+   sharing, notifications, and background refresh.