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	1	# Hutch Roadmap
2	2
3		## Positioning
4
5		Hutch 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
15		The main risk now is not lack of scope. The main risk is shipping too late with
16		an increasingly broad surface area and not enough polish.
17
18		This roadmap treats the current app as a real 1.0 candidate and shifts the
19		focus from feature expansion to launch readiness.
20
21	3	## Version 1.0 Goal
22	4
23	5	Ship a stable SourceHut mobile client with strong support for the most active
		@@ -26,10 +8,12 @@ day-to-day workflows:
26	8	- Browse and manage repositories
27	9	- Browse and manage tickets
28	10	- Browse and manage builds
29		- Support both git and hg repositories
	11	- Support both Git and Mercurial repositories
30	12	- Provide dependable sharing and navigation
31	13
32		Version 1.0 does not need to cover every sr.ht service.
	14	Version 1.0 does not need to cover every SourceHut service.
	15
	16	---
33	17
34	18	## Release Strategy
35	19
		@@ -50,25 +34,25 @@ Focus on quality, not new surface area.
50	34	- Build submission
51	35	- Verify build retry and edit/resubmit flows
52	36	- Verify repository sharing links for:
53		- repository
54		- commit
55		- file
	37	- Repository
	38	- Commit
	39	- File
56	40	- Verify sharing links for:
57		- build
58		- tracker
59		- ticket
60		- profile
	41	- Build
	42	- Tracker
	43	- Ticket
	44	- Profile
61	45	- Review empty/loading/error states across all main tabs
62	46	- Remove any leftover temporary debug logging
63	47	- Audit device-only issues:
64	48	- Xcode attach quirks
65		- on-device auth/cache behavior
	49	- On-device auth/cache behavior
66	50	- WebView rendering performance
67	51
68	52	#### UI/UX polish checklist
69	53
70	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	56	- Confirm toolbar actions are visible and non-duplicated
73	57	- Confirm README rendering is smooth on large repositories
74	58	- Confirm forms behave well on iPhone-sized screens
		@@ -82,6 +66,8 @@ Focus on quality, not new surface area.
82	66	- Finalize support URL / project URL
83	67	- Decide whether TestFlight comes before public launch
84	68
	69	---
	70
85	71	### Phase 2: Version 1.1
86	72
87	73	Add one compact new service surface after launch.
		@@ -99,6 +85,8 @@ Add one compact new service surface after launch.
99	85	- paste.sr.ht is relatively self-contained
100	86	- lists.sr.ht is valuable, but broader in UI and data model scope
101	87
	88	---
	89
102	90	### Phase 3: Version 1.2+
103	91
104	92	Expand 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	94	- lists.sr.ht tab
107	95	- paste.sr.ht creation/editing polish
108	96	- pages.sr.ht management
109		- broader deep-link/share coverage
110		- workflow refinements for builds and tickets
111
112		## What Counts As “Done Enough” For 1.0
113
114		Hutch 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
121		That means `lists.sr.ht`, `paste.sr.ht`, and `pages.sr.ht` are not blockers for
122		the first release.
123
124		## Non-Blockers For 1.0
125
126		These 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
135		These 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
146		Do not add another major service right away.
147
148		Instead:
149
150		1. Run a release-focused polish pass
151		2. Build a strict 1.0 checklist from the current app
152		3. Ship to TestFlight or release publicly
153		4. Use `ROADMAP.md` and `TODO.md` separately:
154		- `ROADMAP.md` for release strategy
155		- `TODO.md` for concrete implementation backlog
	97	- Broader deep-link/share coverage
	98	- Workflow refinements for builds and tickets

SECURITY.md +25 −25

		@@ -2,32 +2,32 @@
2	2
3	3	## Supported Versions
4	4
5		This section outlines which versions of the project are currently receiving
6		security updates.
	5	\|Version\|Supported\|
	6	\|-------\|---------\|
	7	\| 1.x \| ✅ Yes \|
	8	\| < 1.0 \| ❌ No \|
7	9
8		\| Version \| Supported \|
9		\| ------- \| ------------------ \|
10		\| 1.x \| :white_check_mark: \|
11		\| < 1.0 \| :x: \|
	10	---
12	11
13	12	## Reporting a Vulnerability
14	13
15		If you discover a vulnerability, please follow the guidelines below to report
16		it:
17
18		1. Submission: Send your vulnerability report to [security@cleberg.net].
19		Please include a detailed description of the issue, steps to reproduce it,
20		and any relevant context.
21
22		2. Response Time: We aim to acknowledge reports within 3 business days.
23		You will receive updates on the status of your report throughout the process.
24
25		3. Acceptance Criteria: If the vulnerability is confirmed, we will provide
26		you with an estimated timeline for resolution and keep you informed of any
27		updates until the issue is resolved.
28
29		4. Declined Reports: If a reported vulnerability is deemed invalid or out of
30		scope, we will notify you of our decision and provide reasoning for the
31		decline.
32
33		Thank you for helping us improve the security of our project!
	14	If you discover a security vulnerability, do not open a public issue.
	15	Instead:
	16
	17	1. Email your report to [security@cleberg.net](mailto:security@cleberg.net).
	18	Include:
	19	- A detailed description of the vulnerability
	20	- Steps to reproduce
	21	- Any relevant context (e.g., affected versions, environment)
	22	2. Response Time: We will acknowledge your report within 3 business days
	23	and keep you updated on the progress.
	24	3. Resolution: If confirmed, we will:
	25	- Provide an estimated timeline for a fix
	26	- Work with you to verify the resolution
	27	- Credit you for the discovery (if you wish)
	28	4. Declined Reports: If the report is invalid or out of scope, we will
	29	explain why and close the issue.
	30
	31	---
	32
	33	Thank you for helping improve the security of our project!

TODO.md +60 −61

		@@ -1,68 +1,67 @@
1		# Hutch 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.
	1	# TODO
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):
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.
	27	### lists.sr.ht
48	28
49		- Push notifications for builds and tickets: The sr.ht API only supports
50		server-side webhooks (HTTP POST to a URL you control). Delivering push
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.
	29	- Endpoint: [https://lists.sr.ht/graphql](https://lists.sr.ht/graphql)
	30	- Scope: `LISTS:RO`
53	31
54		- Contribution activity / GitHub-style heatmap: No aggregate contributions
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.
	32	Tasks:
58	33
59		- Explore / search (hub.sr.ht): The public hub.sr.ht GraphQL API does not
60		expose repository discovery/search or a projects feed comparable to
61		https://sr.ht/projects.
	34	- Show the authenticated user’s mailing lists
	35	- Allow browsing email threads
	36	- Display individual emails as plain text
62	37
63		- Pronouns on profile: Not exposed in the meta.sr.ht GraphQL schema. The
64		field exists in the web UI but is not available to external API clients.
	38	---
	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
67		marked @internal in the meta.sr.ht schema and is not accessible to external
68		clients.
	60	- Universal links (requires Sourcehut to host an apple-app-site-association
	61	file)
	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)

Commit 62f7e07b7e

Commit `62f7e07b7e`