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=ccleberg_Hutch&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=ccleberg_Hutch)
 6[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=ccleberg_Hutch&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=ccleberg_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- Build job browsing, build detail views, and build submission
19- Inbox and mailing list reading flows
20- Paste browsing, creation, and detail views
21- Profile and account settings, including SSH keys, PGP keys, and personal access token management
22- Deep links for repositories, tickets, and build jobs
23
24Some SourceHut services are still browser-only from within Hutch. Unsupported areas currently open in Safari instead of rendering in-app.
25
26## Requirements
27
28- Xcode with current iOS SDK support
29- iOS Simulator or physical iOS device
30- A SourceHut account
31- A SourceHut personal access token
32
33## Getting Started
34
351. Clone the repository:
36
37   ```sh
38   git clone https://git.sr.ht/~ccleberg/Hutch
39   ```
40
412. Open the project in Xcode.
423. Build and run the app on a simulator or device.
434. On first launch, create or paste a SourceHut personal access token.
44
45You can create a token at:
46
47- `https://meta.sr.ht/oauth/personal-access-tokens`
48
49## Using Hutch
50
51After signing in with a valid token, Hutch presents five primary areas:
52
53- `Home`: dashboard for projects, assigned tickets, recent builds, and inbox access
54- `Repositories`: browse, search, create, and manage repositories
55- `Tickets`: browse trackers, create trackers, and view ticket details
56- `Builds`: inspect build jobs and submit new builds
57- `More`: lists, pastes, settings, and external links for unsupported services
58
59Authentication notes:
60
61- Hutch validates the token against `meta.sr.ht` before saving it
62- The token is stored in the iOS keychain
63- `Reset App Data` removes saved token data, caches, cookies, and local web data from the device
64
65## Development
66
67The project is an Xcode app with tests under `HutchTests`.
68
69Typical workflow:
70
711. Open the workspace or project in Xcode.
722. Select the Hutch app scheme.
733. Build the app.
744. Run the test plan in `Hutch/HutchTests.xctestplan`.
75
76## Contributing
77
78Contributions are welcome. Keep changes scoped, include tests when behavior changes, and open a pull request with a clear summary of the user-facing impact.
79
80## Security
81
82If you discover a security issue, see [SECURITY.md](SECURITY.md).
83
84## License
85
86This project is licensed under the GPL 3.0 or later. See [LICENSE](LICENSE).
87
88## Contact
89
90Questions or feedback: hello@cleberg.net