krz/hutch

an ios client for sourcehut client ios sourcehut swift https://krz.sh/apps/hutch/

Commit 62f7e07b7e

62f7e07b7e8ba23a91aabaa3acca209084889b4b

parent: dcbc2fa103

Unsigned

cmc <hello@cleberg.net> · 2026-03-18 23:42 UTC 

revamp markdown project files

Layout: unified · split

ROADMAP.md +19 −76
@@ -1,23 +1,5 @@
1# Hutch Roadmap 1# Hutch Roadmap
2 2
3## Positioning
4
5Hutch is already beyond a minimal v1. The core SourceHut surfaces are present:
6
7- Authentication with PAT flow
8- Git repositories
9- Mercurial repositories
10- Trackers and tickets
11- Builds
12- Sharing
13- Core settings and app metadata
14
15The main risk now is not lack of scope. The main risk is shipping too late with
16an increasingly broad surface area and not enough polish.
17
18This roadmap treats the current app as a real 1.0 candidate and shifts the
19focus from feature expansion to launch readiness.
20
21## Version 1.0 Goal 3## Version 1.0 Goal
22 4
23Ship a stable SourceHut mobile client with strong support for the most active 5Ship a stable SourceHut mobile client with strong support for the most active
@@ -26,10 +8,12 @@ day-to-day workflows:
26- Browse and manage repositories 8- Browse and manage repositories
27- Browse and manage tickets 9- Browse and manage tickets
28- Browse and manage builds 10- Browse and manage builds
29- Support both git and hg repositories 11- Support both Git and Mercurial repositories
30- Provide dependable sharing and navigation 12- Provide dependable sharing and navigation
31 13
32Version 1.0 does not need to cover every sr.ht service. 14Version 1.0 does not need to cover every SourceHut service.
15
16---
33 17
34## Release Strategy 18## Release Strategy
35 19
@@ -50,25 +34,25 @@ Focus on quality, not new surface area.
50 - Build submission 34 - Build submission
51- Verify build retry and edit/resubmit flows 35- Verify build retry and edit/resubmit flows
52- Verify repository sharing links for: 36- Verify repository sharing links for:
53 - repository 37 - Repository
54 - commit 38 - Commit
55 - file 39 - File
56- Verify sharing links for: 40- Verify sharing links for:
57 - build 41 - Build
58 - tracker 42 - Tracker
59 - ticket 43 - Ticket
60 - profile 44 - Profile
61- Review empty/loading/error states across all main tabs 45- Review empty/loading/error states across all main tabs
62- Remove any leftover temporary debug logging 46- Remove any leftover temporary debug logging
63- Audit device-only issues: 47- Audit device-only issues:
64 - Xcode attach quirks 48 - Xcode attach quirks
65 - on-device auth/cache behavior 49 - On-device auth/cache behavior
66 - WebView rendering performance 50 - WebView rendering performance
67 51
68#### UI/UX polish checklist 52#### UI/UX polish checklist
69 53
70- Tighten wording and error messages across create/edit flows 54- Tighten wording and error messages across create/edit flows
71- Confirm summary tabs feel consistent across git and hg 55- Confirm summary tabs feel consistent across Git and Mercurial
72- Confirm toolbar actions are visible and non-duplicated 56- Confirm toolbar actions are visible and non-duplicated
73- Confirm README rendering is smooth on large repositories 57- Confirm README rendering is smooth on large repositories
74- Confirm forms behave well on iPhone-sized screens 58- Confirm forms behave well on iPhone-sized screens
@@ -82,6 +66,8 @@ Focus on quality, not new surface area.
82- Finalize support URL / project URL 66- Finalize support URL / project URL
83- Decide whether TestFlight comes before public launch 67- Decide whether TestFlight comes before public launch
84 68
69---
70
85### Phase 2: Version 1.1 71### Phase 2: Version 1.1
86 72
87Add one compact new service surface after launch. 73Add one compact new service surface after launch.
@@ -99,6 +85,8 @@ Add one compact new service surface after launch.
99- paste.sr.ht is relatively self-contained 85- paste.sr.ht is relatively self-contained
100- lists.sr.ht is valuable, but broader in UI and data model scope 86- lists.sr.ht is valuable, but broader in UI and data model scope
101 87
88---
89
102### Phase 3: Version 1.2+ 90### Phase 3: Version 1.2+
103 91
104Expand only after the v1 core is stable in the wild. 92Expand only after the v1 core is stable in the wild.
@@ -106,50 +94,5 @@ Expand only after the v1 core is stable in the wild.
106- lists.sr.ht tab 94- lists.sr.ht tab
107- paste.sr.ht creation/editing polish 95- paste.sr.ht creation/editing polish
108- pages.sr.ht management 96- pages.sr.ht management
109- broader deep-link/share coverage 97- Broader deep-link/share coverage
110- workflow refinements for builds and tickets 98- Workflow refinements for builds and tickets
111
112## What Counts As “Done Enough” For 1.0
113
114Hutch is ready for 1.0 when:
115
116- The main flows work reliably on real devices
117- Errors are understandable
118- The app does not feel inconsistent across git/hg/builds/tickets
119- The missing services feel like roadmap items, not broken gaps
120
121That means `lists.sr.ht`, `paste.sr.ht`, and `pages.sr.ht` are not blockers for
122the first release.
123
124## Non-Blockers For 1.0
125
126These should not delay launch:
127
128- Donation page / IAP
129- Broad service parity across all SourceHut products
130- Public repo discovery equivalent to `sr.ht/projects`
131- Advanced creation workflows beyond what the public APIs cleanly support
132
133## Open Product Questions
134
135These are worth deciding before or shortly after launch:
136
137- Should the app be positioned as “SourceHut client” or “SourceHut for git/hg,
138 tickets, and builds” in App Store messaging?
139- Should exact repository lookup live in Repositories search, a dedicated sheet,
140 or both?
141- Should `paste.sr.ht` or `lists.sr.ht` be the first new post-launch tab?
142- Is TestFlight feedback needed before calling the first public build 1.0?
143
144## Recommended Next Step
145
146Do not add another major service right away.
147
148Instead:
149
1501. Run a release-focused polish pass
1512. Build a strict 1.0 checklist from the current app
1523. Ship to TestFlight or release publicly
1534. Use `ROADMAP.md` and `TODO.md` separately:
154 - `ROADMAP.md` for release strategy
155 - `TODO.md` for concrete implementation backlog
SECURITY.md +25 −25
@@ -2,32 +2,32 @@
2 2
3## Supported Versions 3## Supported Versions
4 4
5This section outlines which versions of the project are currently receiving 5|Version|Supported|
6security updates. 6|-------|---------|
7| 1.x | ✅ Yes |
8| < 1.0 | ❌ No |
7 9
8| Version | Supported | 10---
9| ------- | ------------------ |
10| 1.x | :white_check_mark: |
11| < 1.0 | :x: |
12 11
13## Reporting a Vulnerability 12## Reporting a Vulnerability
14 13
15If you discover a vulnerability, please follow the guidelines below to report 14If you discover a security vulnerability, **do not open a public issue**.
16it: 15Instead:
17 16
181. **Submission**: Send your vulnerability report to [security@cleberg.net]. 171. **Email** your report to [security@cleberg.net](mailto:security@cleberg.net).
19 Please include a detailed description of the issue, steps to reproduce it, 18 Include:
20 and any relevant context. 19 - A detailed description of the vulnerability
21 20 - Steps to reproduce
222. **Response Time**: We aim to acknowledge reports within **3 business days**. 21 - Any relevant context (e.g., affected versions, environment)
23 You will receive updates on the status of your report throughout the process. 222. **Response Time**: We will acknowledge your report within **3 business days**
24 23 and keep you updated on the progress.
253. **Acceptance Criteria**: If the vulnerability is confirmed, we will provide 243. **Resolution**: If confirmed, we will:
26 you with an estimated timeline for resolution and keep you informed of any 25 - Provide an estimated timeline for a fix
27 updates until the issue is resolved. 26 - Work with you to verify the resolution
28 27 - Credit you for the discovery (if you wish)
294. **Declined Reports**: If a reported vulnerability is deemed invalid or out of 284. **Declined Reports**: If the report is invalid or out of scope, we will
30 scope, we will notify you of our decision and provide reasoning for the 29 explain why and close the issue.
31 decline. 30
32 31---
33Thank you for helping us improve the security of our project! 32
33**Thank you for helping improve the security of our project!**
TODO.md +60 −61
@@ -1,68 +1,67 @@
1# Hutch TODO 1# TODO
2
3## Claude Code, Codex, & Mistral Prompting Notes
4
5- **Always start a new session with the project context block** (see
6 hutch-ios-prompts.md prompt 0) so the agent knows the API conventions.
7- **Keep prompts short and specific.** Long prompts waste context. One bug or
8 feature per prompt. Paste console output and error messages directly instead
9 of describing them.
10- **When a fix fails twice, ask the agent to print raw state first** (raw API
11 response, current file contents, exact variable values) before attempting
12 another fix. Blind retries consume context without progress.
13- **Never paste full file contents into the prompt.** Ask the agent to read
14 the file itself using its file tools.
15- **Batch only tightly related changes.** Unrelated changes in one prompt
16 increase the chance of partial failure and wasted context on rollback.
17
18## Features
19
20- **Exact repository lookup**: Since public repository discovery/search is not
21 exposed in the public sr.ht API, add a manual `~owner/repo` lookup flow that
22 can open git.sr.ht or hg.sr.ht repositories directly.
23
24- **paste.sr.ht tab**: Paste support. Endpoint:
25 https://paste.sr.ht/graphql. Show the authenticated user's pastes, allow
26 viewing individual pastes, and support creating new pastes. Required scope:
27 PASTES:RO for browsing, PASTES:RW for creation/editing.
28
29- **lists.sr.ht tab**: Mailing list support. Endpoint:
30 https://lists.sr.ht/graphql. Show the authenticated user's mailing lists,
31 allow browsing email threads, and display individual emails as plain text.
32 Required scope: LISTS:RO.
33
34- **pages.sr.ht tab**: Site management support. Endpoint:
35 https://pages.sr.ht/graphql. Show the authenticated user's published sites,
36 site metadata, publishing status, and access control where supported. This is
37 for managing Pages sites, not browsing public project discovery.
38
39- **Donation page / IAP**: Add a donation/support page once the App Store /
40 StoreKit setup is ready.
41 2
42## Out of Scope 3---
4
5## TODO List
6
7### Core Functionality
8
9- Implement manual `~owner/repo` lookup flow for opening git.sr.ht or hg.sr.ht
10 repositories directly
11
12---
13
14### paste.sr.ht
15
16- **Endpoint:** [https://paste.sr.ht/graphql](https://paste.sr.ht/graphql)
17- **Scope:** `PASTES:RO` (browsing), `PASTES:RW` (creation/editing)
18
19**Tasks:**
20
21- Show the authenticated user’s pastes
22- Allow viewing individual pastes
23- Support creating new pastes
24
25---
43 26
44- **Universal links** (e.g. tapping a git.sr.ht URL in Safari opens Hutch): 27### lists.sr.ht
45 Requires Sourcehut to host an apple-app-site-association file on their
46 servers. This is outside our control. The hutch:// custom URL scheme works as
47 a fallback for links we generate ourselves.
48 28
49- **Push notifications for builds and tickets**: The sr.ht API only supports 29- **Endpoint:** [https://lists.sr.ht/graphql](https://lists.sr.ht/graphql)
50 server-side webhooks (HTTP POST to a URL you control). Delivering push 30- **Scope:** `LISTS:RO`
51 notifications to iOS would require a backend relay server to receive webhooks
52 and forward them via APNs. Out of scope for a personal app with no backend.
53 31
54- **Contribution activity / GitHub-style heatmap**: No aggregate contributions 32**Tasks:**
55 endpoint exists in the sr.ht GraphQL API. Computing this would require
56 paginating every repository's full commit log and filtering by author --
57 extremely slow and not practical.
58 33
59- **Explore / search (hub.sr.ht)**: The public hub.sr.ht GraphQL API does not 34- Show the authenticated user’s mailing lists
60 expose repository discovery/search or a projects feed comparable to 35- Allow browsing email threads
61 https://sr.ht/projects. 36- Display individual emails as plain text
62 37
63- **Pronouns on profile**: Not exposed in the meta.sr.ht GraphQL schema. The 38---
64 field exists in the web UI but is not available to external API clients. 39
40### pages.sr.ht
41
42- **Endpoint:** [https://pages.sr.ht/graphql](https://pages.sr.ht/graphql)
43
44**Tasks:**
45
46- Show the authenticated user’s published sites
47- Display site metadata, publishing status, and access control where supported
48- For managing Pages sites, not browsing public project discovery
49
50---
51
52### Donation Page / In-App Purchases
53
54- Add a donation/support page once the App Store / StoreKit setup is ready
55
56---
57
58## Out of Scope
65 59
66- **Revoke personal access tokens**: The revokePersonalAccessToken mutation is 60- Universal links (requires Sourcehut to host an apple-app-site-association
67 marked @internal in the meta.sr.ht schema and is not accessible to external 61 file)
68 clients. 62- Push notifications for builds and tickets (requires a backend relay server)
63- Contribution activity / GitHub-style heatmap (no aggregate endpoint,
64 impractical to compute)
65- Explore / search (hub.sr.ht) (no public discovery API)
66- Pronouns on profile (not in GraphQL schema)
67- Revoke personal access tokens (`@internal` in schema, inaccessible)