krz/hutch

 1# Hutch
 2iOS client for SourceHut.
 3
 4[![builds.sr.ht status](https://builds.sr.ht/~ccleberg/Hutch.svg)](https://builds.sr.ht/~ccleberg/Hutch?)
 5[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=zerolabsco_hutch&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=zerolabsco_hutch)
 6[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=zerolabsco_hutch&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=zerolabsco_hutch)
 7
 8## Overview
 9
10Hutch is a native SwiftUI app for browsing and managing SourceHut services on iPhone and iPad. It uses SourceHut's GraphQL APIs and stores your personal access token in the iOS keychain.
11
12The app currently includes:
13
14- Home dashboard with assigned tickets, recent builds, and projects
15- Repository browsing for Git and Mercurial repositories
16- Repository details including README, references, commits, diffs, files, artifacts, and settings
17- Artifact upload and deletion on release tags
18- Tracker and ticket browsing, ticket detail views, and tracker creation
19- Ticket editing and deletion, with subscriptions for tickets and trackers
20- Build job browsing, build detail views, and build submission
21- Inbox and mailing list reading flows
22- Patchset review: cover letters, per-patch diffs, checks, version chains, and status changes
23- Mailing list creation, settings, and deletion
24- Paste browsing, creation, and detail views
25- Profile and account settings, including SSH keys, PGP keys, personal access token management, and the audit log
26- Email preferences for todo.sr.ht and lists.sr.ht
27- Deep links for repositories, tickets, and build jobs
28
29Some SourceHut services are still browser-only from within Hutch. Unsupported areas currently open in Safari instead of rendering in-app.
30
31## Requirements
32
33- Xcode with current iOS SDK support
34- iOS Simulator or physical iOS device
35- A SourceHut account
36- A SourceHut personal access token
37
38## Getting Started
39
401. Clone the repository:
41
42   ```sh
43   git clone https://git.sr.ht/~ccleberg/Hutch
44   ```
45
462. Open the project in Xcode.
473. Build and run the app on a simulator or device.
484. On first launch, create or paste a SourceHut personal access token.
49
50You can create a token at:
51
52- `https://meta.sr.ht/oauth2/personal-token`
53
54## Using Hutch
55
56After signing in with a valid token, Hutch presents five primary areas:
57
58- `Home`: dashboard for projects, assigned tickets, recent builds, and inbox access
59- `Repositories`: browse, search, create, and manage repositories
60- `Tickets`: browse trackers, create trackers, and view ticket details
61- `Builds`: inspect build jobs and submit new builds
62- `More`: lists, pastes, settings, and external links for unsupported services
63
64Authentication notes:
65
66- Hutch validates the token against `meta.sr.ht` before saving it
67- The token is stored in the iOS keychain
68- `Reset App Data` removes saved token data, caches, cookies, and local web data from the device
69
70## Development
71
72The project is an Xcode app with tests under `HutchTests`.
73
74Typical workflow:
75
761. Open the workspace or project in Xcode.
772. Select the Hutch app scheme.
783. Build the app.
794. Run the test plan in `Hutch/HutchTests.xctestplan`.
80
81## Contributing
82
83Contributions are welcome. Keep changes scoped, include tests when behavior changes, and open a pull request with a clear summary of the user-facing impact.
84
85## Security
86
87If you discover a security issue, see [SECURITY.md](SECURITY.md).
88
89## License
90
91This project is licensed under the GPL 3.0 or later. See [LICENSE](LICENSE).
92
93## Contact
94
95Questions or feedback: hello@cleberg.net