Knotless for iOS

A native app for reading knotless: inbox, pulls and their diffs, repositories and profiles. SwiftUI, iOS 18 and up, no dependencies. It reads knotless.dev's XRPC queries and writes through its procedures.

The project is generated, so edit project.yml, not an .xcodeproj:

brew install xcodegen
ios/run.sh                        # builds and runs in the simulator
KNOTLESS_ACTOR=<handle> ios/run.sh inbox

Signing in

The app signs in through a browser, ending with the session a page's cookie would hold, kept in the keychain and sent as that cookie (docs/design/serve.md, Logging in).

A debug build can also ask as an account without signing in: with goat logged in and KNOTLESS_ACTOR set, run.sh mints an hour's service token for each method into build/.tokens.json and hands the app its path. That code isn't in a release build.

TestFlight

Raise CURRENT_PROJECT_VERSION in project.yml for each upload, then:

cd ios && xcodegen generate
xcodebuild archive -project Knotless.xcodeproj -scheme Knotless -configuration Release \
  -destination 'generic/platform=iOS' -archivePath build/Knotless.xcarchive -allowProvisioningUpdates
xcodebuild -exportArchive -archivePath build/Knotless.xcarchive -exportPath build/export \
  -exportOptionsPlist ExportOptions.plist -allowProvisioningUpdates

build/export/Knotless.ipa goes up with Xcode's Organizer or Transporter. Signing in needs webcredentials on Apple's CDN (https://app-site-association.cdn-apple.com/a/v1/knotless.dev), as a release build can't use developer mode: it can take a day or two after the file changes.

Making everyone update

An appview's dev.knotless.describeServer can name the oldest build it lets run. A build older shows only a screen with a way to update, in place of the whole app, with the reason if there is one:

# in .knotless/workflows/deploy.yml, landed as any pull
KNOTLESS_IOS_MINIMUM_BUILD: "5"
KNOTLESS_IOS_MINIMUM_REASON: "This version can lose what you write."

The number is CURRENT_PROJECT_VERSION. Raise it only once that build, or a newer one, is live for the people it stops, on the App Store and on TestFlight: the screen is all they can see, and there is nothing else to send them to. Taking the setting out lets them back in, the next time the app comes to the front.

The app asks when it comes to the front and keeps the answer, so a build stopped stays stopped offline, and one that has never been told runs. A server that doesn't answer changes nothing. Its button opens TestFlight in a TestFlight build and the App Store in any other. Only builds from 5 up do this: older ones ignore the setting.

Sizes and colours

Every colour, space, corner radius, icon and avatar size is a token in Knotless/Support/Theme.swift or Knotless/Support/Palette.swift: take one by name, and add one there when none fits. The spaces follow the scale in web/src/tokens.css. Never take an iOS colour, as Color(.systemBackground) or Color.secondary, directly: the tokens stand for those where there's no theme, and for a theme's colours where there is.

Themes

The app is drawn in the themes the pages are. Settings, Appearance chooses: Same as knotless.dev (the default) follows the account's appearancePref, day and night pair included; Automatic, Light and Dark are iOS's own colours; then the themes the pages offer by name, and the account's own, those it published and those it added. A palette leaves out what the pages fill in, and Palette(record:) fills it in as tokens.css does.

A theme's colours come in as each is drawn: a token is a dynamic UIColor that reads the theme in use (Themes), and a trait carried from the root (ThemeTrait) draws them again when it changes, without rebuilding a screen. As on the pages, only the main button takes a colour, the theme's primary under its onPrimary; a state's pill is its colour under onSolid; and a button beside the main one is quietButton, on the theme's surface.

Looking at a screen

just ios-look <screen> draws a screen in the simulator, light and dark, from all the way down, as pictures in target/look, with no server and no account. Look at what you changed before you push it:

just ios-look pull-open
just ios-look pull-open --set getMergeStatus.checks=failed --top --light
just ios-look pull-open --tap "Add to merge queue" --light
just ios-look pull-open --theme dracula --dark
just ios-look appearance --tap Ember

Its answers are what harness/shots/fixtures.json recorded for the web pages, with what that lacks in look-answers.json. A write does nothing, so a --tap that writes shows what's under way, not what comes after. ios/look.mjs lists the screens and options. Each run starts with Appearance as a new install has it, whatever the simulator was left in. It needs Xcode, so no check runs it.

Tests

KnotlessUITests taps through the app against live knotless.dev. It needs the network and those tokens, and CI doesn't build iOS, so it is run by hand:

TEST_RUNNER_KNOTLESS_TOKENS=$PWD/ios/build/.tokens.json \
xcodebuild test -project ios/Knotless.xcodeproj -scheme Knotless \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
  -derivedDataPath ios/build -allowProvisioningUpdates

CI can't build the app, as Xcode needs macOS. On a pull, its ios check compiles Knotless/API/Models.swift on Linux and reads the recorded XRPC answers with it: ios/check-models.sh runs the same here.

Diagrams

A Mermaid block in Markdown is drawn by Pele, as the pages draw it (Knotless/Support/Diagram.swift). Knotless/Vendor/pele.js is the version web/package-lock.json pins: after raising it there, just ios-pele copies it here, and the ios check fails while the two differ.

Icons

Assets.xcassets holds Octicons (MIT), the same set the web pages draw.