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