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- Tracker and ticket browsing, ticket detail views, and tracker creation
18- Ticket editing and deletion, with subscriptions for tickets and trackers
19- Build job browsing, build detail views, and build submission
20- Inbox and mailing list reading flows
21- Patchset review: cover letters, per-patch diffs, checks, version chains, and status changes
22- Paste browsing, creation, and detail views
23- Profile and account settings, including SSH keys, PGP keys, and personal access token management
24- Email preferences for todo.sr.ht and lists.sr.ht
25- Deep links for repositories, tickets, and build jobs
26
27Some SourceHut services are still browser-only from within Hutch. Unsupported areas currently open in Safari instead of rendering in-app.
28
29## Requirements
30
31- Xcode with current iOS SDK support
32- iOS Simulator or physical iOS device
33- A SourceHut account
34- A SourceHut personal access token
35
36## Getting Started
37
381. Clone the repository:
39
40   ```sh
41   git clone https://git.sr.ht/~ccleberg/Hutch
42   ```
43
442. Open the project in Xcode.
453. Build and run the app on a simulator or device.
464. On first launch, create or paste a SourceHut personal access token.
47
48You can create a token at:
49
50- `https://meta.sr.ht/oauth2/personal-token`
51
52## Using Hutch
53
54After signing in with a valid token, Hutch presents five primary areas:
55
56- `Home`: dashboard for projects, assigned tickets, recent builds, and inbox access
57- `Repositories`: browse, search, create, and manage repositories
58- `Tickets`: browse trackers, create trackers, and view ticket details
59- `Builds`: inspect build jobs and submit new builds
60- `More`: lists, pastes, settings, and external links for unsupported services
61
62Authentication notes:
63
64- Hutch validates the token against `meta.sr.ht` before saving it
65- The token is stored in the iOS keychain
66- `Reset App Data` removes saved token data, caches, cookies, and local web data from the device
67
68## Development
69
70The project is an Xcode app with tests under `HutchTests`.
71
72Typical workflow:
73
741. Open the workspace or project in Xcode.
752. Select the Hutch app scheme.
763. Build the app.
774. Run the test plan in `Hutch/HutchTests.xctestplan`.
78
79## Contributing
80
81Contributions are welcome. Keep changes scoped, include tests when behavior changes, and open a pull request with a clear summary of the user-facing impact.
82
83## Security
84
85If you discover a security issue, see [SECURITY.md](SECURITY.md).
86
87## License
88
89This project is licensed under the GPL 3.0 or later. See [LICENSE](LICENSE).
90
91## Contact
92
93Questions or feedback: hello@cleberg.net