Elegant Chaos

Fixing The ActionBuilder Plugin

Fri, 27 Feb 2026 00:00:00 +0000

In a previous post, I mentioned a command line tool that I built which you can point at a Swift package, and which will generate a GitHub Actions workflow file for it.

I also built a SwiftPM plugin which invokes the tool, but at some point it stopped working. Instead of running, it would just hang, for reasons unknown.

The Deadlock

The root cause turned out to be nested SwiftPM invocations.

The plugin launches ActionBuilderTool, and the tool calls swift package dump-package to inspect metadata and infer sensible workflow defaults.

I think that did work, at some point in the past, but changes in Swift Package Manager appear to have broken it. When the swift command line tool runs the plugin, which runs the tool, which runs swift, you end up with lock contention around index.lock, and everything grinds to a halt.

The fix I found was to make the tool’s swift package dump-package use an isolated scratch path inside a subfolder of the .build folder. This means that the inner invocation doesn’t fight with the outer one, and it’s still in a place that we can write to.

The workaround isn’t ideal, since building to a different scratch path means doing a lot of work again, but this isn’t a command that you run that often.

I’d like to find a better fix, but for now, it works.

To make the behavior explicit, I added a --called-from-plugin flag. The plugin uses this, but if you just want to use the tool manually, you don’t need to.

Unexpected Lack Of Items In The Bagging Area…

I thought I was done at this point, and made a new release, only to discover that it was broken and not doing anything at all.

🤔

I eventually tracked that down to an issue with nested sandboxes. The tool invocation was silently failing when the plugin called it, but the plugin wasn’t reporting anything. The failure was because it was trying to sandbox inside a sandbox. Invoking the inner swift package dump-package without sandboxing seems to sort that out - and hopefully it’s still safe since the plugin itself is running sandboxed.

Smoke Em If You Got Em

I fixed the problem, eventually, after a lot of head scratching.

In doing so I also improved the plugin diagnostics so it now reports a proper error if the tool exits non-zero, and explicitly checks that the expected workflow file was actually produced.

I then added smoke tests for:

direct tool workflow generation
tool generation in plugin-mode
actual swift package plugin invocation

Obviously I then used the tool on the plugin source code itself, to generate a workflow file which runs these tests in an action.

Hopefully that will stop me from releasing a broken plugin next time…

Other Fixes In Passing

While I was in there, I also tidied up a few other things in ActionBuilderCore, which is the underlying library that the tool uses to do the generation:

bumped the supported Swift versions and moved the minimum up to 5.10
updated the GH images that the workflow uses; some of them had become obsolete
reduced generated workflow noise and improved log handling
removed some stale dependencies and legacy code paths

There’s a bunch more polishing I’d like to do, but at least the “plugin hangs forever” issue is no longer one of the mysteries of the universe.

Part of the reason I started doing all of this in the first place is that I decided to revive and update Action Status, and I needed some actual running workflows to point it at. Which led me to my discovery of the broken plugin. And thus another rabbit hole was entered.

More about the Action Status refresh anon…

Oh, if you’re interested, you can find the plugin here.

Localizable String Catalogues in Swift Packages

Thu, 12 Feb 2026 00:00:00 +0000

I’ve been slowly splitting The Stack up into small internal Swift packages.

Unfortunately, if you use localizable string catalogues in Xcode, there are a few wrinkles.

Lots Of Small Targets

I’ve been splitting Xcode app projects into multiple packages for a few years now.

Mihaela Mihaljevic wrote about something similar a while ago. Some of the details in that post are different, but the basic idea is similar to what I do.

I find it a good way to minimize entangled dependencies, and it has other advantages.

It gives you an obvious place to put a small targeted set of unit tests, it can help with SwiftUI preview performance, and it lets you build and test a lot of code without the need for Xcode.

Using Catalogues In Packages

If you just want localised strings in a package, the basics are straightforward:

set defaultLocalization in Package.swift
put your catalogue in Sources/MyTarget/Resources/Localizable.xcstrings
tell Package.swift to process the resource file

Something like this:

let package = Package(
  name: "StackCore",
  defaultLocalization: "en",
  // ...
  targets: [
    .target(
      name: "StackCommands",
      resources: [.process("Resources")]
    )
  ]
)

If you’re only using Xcode, this mostly works.

Which Catalogue Was It Again?

By default, localization lookup assumes that the strings are in your main bundle.

That is fine for apps, but not so fine for strings that actually live inside a package target.

You can force this to work in a library target by being explicit:

LocalizedStringResource("show.active", bundle: .module)

That works, but it is noisy, and is particularly clunky in SwiftUI views where the visual clutter detracts from otherwise clean code. It is also easy to forget to add the extra bundle parameter.

A nicer option is to get Swift to generate symbols for your localization keys, and to use these directly from code:

public let name = String(localized: .actionNew)
Text(.settingsHotkeyHelp(appName))

One benefit of this is that if the key changes, the generated symbol name will change, and your code won’t build. No more mismatched keys.

However, another benefit specifically useful for libraries is that those generated constants carry the right context. If you use the generated symbol in a place that expects a localizable string, it will automatically pull it from the correct bundle.

This is nice. Less boilerplate, fewer mistakes with keys, and localizations close to the code that uses them.

Building Outside Xcode

There is another wrinkle if you build packages from the command line.

If you build within Xcode, or with the xcodebuild command line tool, symbol generation for .xcstrings happens automatically, even for SwiftPM library targets.

If you build with swift build or swift test however, it doesn’t. This is because Swift Package Manager does not support string catalogs out of the box.

Luckily, there is a command line tool to do the required work:

xcrun xcstringstool generate-symbols ...

It’s easy enough to write a small SwiftPM plugin to call that tool for each of your targets.

That solves command-line builds, but introduces a new problem: when Xcode does its own generation, it will run your plugin too, so you end up with duplicate symbols.

The way around this is to only apply the plugin when the build is not being driven by Xcode.

In your Package.swift you can work around this with a small environment check¹:

#if canImport(Darwin)
import Darwin
let buildingInXcode = Context.environment["__CFBundleIdentifier"]?.contains("Xcode") ?? false
#else
let buildingInXcode = false
#endif

let localizationPlugins: [Target.PluginUsage] = buildingInXcode ? [] : [.plugin(name: "StackStringCatalogSymbols")]

Then targets that own catalogues just use plugins: localizationPlugins.

It’s a little bit of plumbing, but it keeps both worlds happy: Xcode builds and command-line SwiftPM builds.

Other Possible Patterns

I did wonder whether having all the localizations split up like this is actually a good idea in the first place? You do end up with a lot of different catalogues, which could be hard to maintain.

Maybe, instead, localization should be a layer that you only add at the application level? That way they’re all in one place, and different apps could even use the same library but overlay different localizations.

Unfortunately, if you want to use the generated string symbols in your code, your code needs to be able to see them. If the code is in a library, the symbol has to also be generated by that library, or visible to it.

Following this line of reasoning a bit further, could I make a library target with all the localizations in it, and then import that from the libraries that want to use the symbols?

This would still tie a library to a specific set of localizations for its keys, but at least all the strings would be in a single catalogue, which might be easier to manage.

Sadly this doesn’t work either, because the code generator, that creates the symbols, declares them as internal. You don’t get a free, public, cross-package symbol API that every other target can just import and use 😢.

For now, I’ve stuck with per-target catalogues in the Stack, each local to the package that owns the UI or command surface.

This feels consistent with the rest of the architecture. Generally the Stack code is factored into services that are responsible for one aspect of the application. Each service target owns its commands, views, tests, logic and resources - including strings.

Currently, I like this setup. Your Mileage May Vary™.

Thanks to Gwynne for pointing me in the right direction with this check. I originally tried importing Foundation and looking at the environment with ProcessInfo, but I couldn’t find something that was reliably set by Xcode and not by SwiftPM. Using Context works, and also removes the Foundation import, which is apparently best avoided. ↩

SwiftUI Navigation Pain

Fri, 12 Dec 2025 00:00:00 +0000

One of the things I’ve wanted to do with The Stack is to handle all of the user’s interactions with some sort of action abstraction.

It turns out that this is harder than it ought to be with the modern SwiftUI navigation mechanisms.

SwiftUI’s modern navigation uses NavigationStack instead of the older NavigationView, and it’s definitely an improvement on what came before.

The basic idea is:

you bind the NavigationStack view to some sort of model representing the route/path that is currently visible
ideally you use the type-erased NavigationPath for this purpose
whenever possible, you let SwiftUI manipulate the route for you using NavigationLink, the default back button, and/or @Environment(\.dismiss)
this pushes items onto the route and pops them off (you can also do this explicitly yourself)
you use .navigationDestination to teach SwiftUI which view to use to back each kind of item

Doing this has some nice benefits.

The view and models stay loosely coupled, and there is no one place in the code where you have to tell the NavigationStack about everything that might get pushed onto it.

The places where you do the pushing/popping can work in terms of the model or some other abstract notion of what is being presented, without needing to know anything about that actual views that will be used.

You can also put your NavigationPath instance into a router class and inject that into the environment. This lets you fish it out from anywhere and manipulate the route explicitly. For example you can implement deep links by splitting them up into items and pushing those items into the route. SwiftUI will see that the route has changed, and sort out the details of animating from where you were to where you’re going.

Actions

For The Stack (and my other apps), I want to define all the user’s interactions as abstract actions. This includes navigation actions.

I want each thing that the user can do to be represented by something that implements a Command protocol. The user will tap or click something, which will cause a Command to be performed, and the perform method of the command will do the actual mutations of the model or view-model. This will probably result in one or more updates to the UI, which the user will then interact with, and the cycle will repeat.

One reason for doing things this way is to allow the same actions to be triggered from multiple places without duplicating code. I can define a single Command for something like making a new note, and have a menu item, a button, a toolbar item, an app intent, or a siri command all invoke it.

This is especially helpful when targetting an application on multiple platforms that support different interaction mechanisms.

Another reason is that I can write common code once to take any Command and have it build the UI for me. If my command abstraction has enough information (for example a label and icon to use to represent the command, maybe an optional shortcut or tooltip), then some generic code can create a button for the command, implement the app intent for the command, insert the menu item for the command, and so on. This reduces boilerplate, and enhances consistency.

A third reason is that I can use this abstraction to support undo/redo at a level that makes sense to me. Foundation’s UndoManager has been around a long time, and is integrated into a lot of systems, including SwiftData, but it works at too granular a level for me. On this topic, I very much agree with what Drew McCormack says in this comment. I would prefer to define undo at a high level.

Finally, funnelling everything that the user does through a single mechanism allows me to support analytics and auditing.

I don’t want to know what any specific user is doing, but I would like some general analytics on usage patterns. What features to people use? What do they miss? After using feature A, do they usually choose B, or C (or rage quit in disgust!)?

Also, there is some need to monetize the applications I make! I have always been a proponent of what I would call “true micropayments”, by which I mean really charging tiny amounts for small actions, such that the user genuinely pays nothing if they don’t launch your app for weeks or months.

I’d like to try to do monetization this way. In order to do this, I need a reliable mechanism to record not what actions my users are taking, but perhaps just how many actions they’ve taken. I can then come up with a formula which ties this to real money in some way.

Unfortunately, using NavigationLink, the default back button, and/or @Environment(\.dismiss) does not lend itself particularly well to the action-based approach I’ve outlined above.

If I use NavigationLink, there is no way to ask it to invoke one of my actions when it is selected. Similarly when the user taps the default back button, or a button that calls the dismiss() method supplied by the environment.

The view-model manipulation of the route is just done for you in these cases. That means that if you want all of your navigation to be done through actions, you’re out of luck unless you make your own UI elements. This isn’t hard to do, but it is a bit annoying, and you can lose behaviour that you’d otherwise get for free. Given the fragility of SwiftUI, I prefer to give it as much semantic information as I can. Using NavigationLink tells SwiftUI more about what’s really going on, compared to just using Button. I don’t like the fact that I might be losing some clever behaviour (possibly future behaviour) if I don’t do that.

Watching The Path

A possibly solution to this problem is to allow SwiftUI to manipulate the route, but bind to the path variable and watch it for changes - for example using .onChange in my root content view.

When a change to the path happens, we can work out what it is and issue a ‘fake’ command to our action system, so that the interaction is recorded and can be audited, undone, etc. This isn’t great, but it might be better than the alternative of abandoning the recommended UI mechanisms.

Unfortunately this is pretty much impossible to achieve if you use SwiftUI’s NavigationPath to represent your route!

NavigationPath is a type-erased list of the items in your stack. The type erasure is good in that it works regardless of what you throw into it, which in turn means that you can use .navigationDestination the way that it is intended to be used, which is to declare an individual destination for each type that you place on the stack. This is important for keeping things loosely coupled - and so using NavigationPath is recommended.

Unfortunately, NavigationPath only lets you manipulate the path by adding or removing items from it, and the only information you can obtain about the current state is how many items are on it. At the point that a user taps on a NavigationLink, SwiftUI still has enough information to supply the linked value to the closure that you gave to .navigationDestination as an actual typed instance.

Sadly, it doesn’t seem to allow you retrieve a value from the path later. You can’t say, for example, “what’s the value on the top of the stack?”.

The upshot of this is that if you watch for changes to NavigationPath instance, all you can tell is that its length has changed!

If the length reduced, you know that the user popped, but if the length increased, you know that the user pushed something, but not what it was. This is not much use for generating fake navigation commands!

Not Using `NavigationPath`

There is an alternative approach.

NavigationStack allows you to supply a binding to a collection of anything hashable, and so you don’t strictly have to use NavigationPath.

You could, instead, define an enum with all the various kinds of things you want to push, and bind to an array of your enum type.

This works, and when you watch your array, you know exactly what kinds of things it contains, and so you can issue the relevant fake commands.

The downside of this approach is that there’s more coupling. You have a single enum that has to know about all of the things that you are going to push, and you will end up with a single .navigationDestination call for the enum type.

Imperfect Solutions

Binding to a path which is an array of enum (or some other custom type) values isn’t wrong, per-se. It is probably what I’ll need to do if I want to fully support recording commands for all of the user’s navigations.

It seems to me that it defeats much of the point of the way NavigationStack has been designed though.

In any case, personally I really wish I didn’t have to take the approach of watching mutations to the path in the first place 😢.

It would be far better if I could register a single hook with the NavigationStack. This would be called with a path manipulation to perform (push/pop/reset), and allowed to do it however it wanted to. I could use this hook to dispatch commands through my action system, and they would change the path.

This would allow me use all of the other navigation mechanisms that SwiftUI has supplied me.

Currently I’ve adopted a hybrid approach:

I don’t watch the path.
I use custom buttons instead of NavigationLink, and they issue navigation commands to change the route
I use the default SwiftUI back button, and accept that I’m not currently capturing the user popping views off the stack

Tune In Next Time…

Another possible approach to this problem might be to use .onAppear/.onDisappear on the views themselves, and somehow have them generate the navigation events that way.

This would also solve another problem that I have, which is that I’ve some global UI components that I would like to always be present, but to react differently depending on what’s currently at the top of the navigation stack.

Unfortunately, relying on .onAppear/.onDisappear also has a number of problems!

Originally I’d intended to cover those in this post too, but it’s getting a bit wordy, so I think I will leave that one for another day…

Am I Holding It Wrong?

As always, this post reflects my imperfect understanding of SwiftUI. Have I missed something? If so, let me know. I’d be delighted!

All Quiet In The Western Isles

Fri, 05 Dec 2025 00:00:00 +0000

I’ve been a bit quiet and not posted for the last few weeks.

This is down to a combination of holidays, minor sickness, distractions, and beavering away preparing an MVP of The Stack, which I’ve now released.

I’ve also got a bit of a backlog of other things I mean to post about…

… but they will have to wait for another day.

Potential topics include:

the solution I settled on for abstracting menus, buttons and toolbar items in SwiftUI
extending my action abstraction to support siri, shortcuts and intents
more refinements to my Release Tools
localized strings in packages
plenty more updates to The Stack
potential next projects

The Stack

Thu, 04 Dec 2025 00:00:00 +0000

I’ve just quietly released the first version of The Stack.

It represents a slightly different and fairly opinionated take on solving the To Do list / note taking problem, and I made it mostly to scratch my own itches¹. I’m hoping that some other people think the way I do and will also find it useful.

You can download it here.

For some more detailed answers as to why I made it, read on…

Isn’t This A Solved Problem?

Well, yes, sort of.

To Do lists are paradoxical though. Much like Rimmer’s revision timetable in Red Dwarf, they can become a distraction and a source of anxiety.

The Stack Isn’t Reminders

There are some categories of thing-to-remember where an app like Reminders is perfect. It’s helpful to be able to set alerts, especially . It’s helpful to be able to have multiple lists, and to share them with other people.

I use Reminders to alert me to things that repeat periodically (“file your taxes”, “put the bins out”, etc). I also use it to share a shopping list with my partner.

The Stack definitely isn’t trying to be that kind of app.

The Stack Isn’t A Methodology

There are some mature methodologies in this problem space - one of the best known being Get Things Done.

There are some great apps out there to support these methodologies, and if you swear by a methodology then you probably want an app that supports you - lets you put tasks into buckets, or give them colors, or group them in a way that makes sense for the methodology.

The Stack isn’t trying to be that kind of app either. Or, at least, it’s not trying to support another methodology. Arguably, it’s trying to introduce a new one, albeit a very lightweight one.

The Stack Isn’t An Issue Tracker

When trying to keep track of tasks, at the heavier end of the spectrum are fully-fledged issue tracking system.

If you’re in a team, the ability to share tasks with everyone, prioritize them and plan them, set deadlines, add keywords, etc, etc, is essential.

Even if you’re working on your own, the features of issue trackers may be helpful for you.

There are plenty of issue tracker apps out there for you. The Stack isn’t one of them!

So What’s Left?

The full name of my app is actually “The Stack - Notes To Self”, and that should give you a clue as to where I think it fits.

When I’m in the middle of something, and an idea pops into my head, I just want to record it and move on. This is what I call a “note to self”.

What matters most to me in this situation is just to capture the thought.

I don’t want to have to think about which list it goes in. I don’t really want to have to think about dates or priorities or any of that stuff.

I find having to make those decisions is off-putting and can slow me down or even paralyze me into indecision.

Even as a solo software developer, I find that I don’t really need a proper issue tracker a lot of the time. I’ve used many different trackers, and have come to realize that the simpler they were, the fewer options and fields they had, the more I liked them.

The Stack is built for these situations.

It isn’t intended to replace your shopping list app, or your issue tracking database, although it can, if you want it to.

It can complement a methodology-based app (or perhaps, it can replace the methodology with a simpler one?).

Triage?

The Stack is essentially just a sequential list of notes, with the latest at the top.

You may be worried that this will rapidly get too big and unruly, and you’ll not be able to find anything.

I can understand this concern, and if you want, you can think of it as just being for initial capture of thoughts.

You can then triage them periodically and move into other more permanent places, that the the stack itsef stays quite light and empty.

I don’t use it that way, but you can if you want.

A Big Heap ‘O Stuff

My idea is that it will work even when there are lots of notes in the stack, and it feels a bit like a big heap of unsorted stuff.

Embrace the Chaos, I say!

It is perhaps counter-intuitive, but I actually suspect that many notes get added to many to-do lists in many apps, and then never actually actioned.

My thesis is that it’s more important to just capture quickly and move, on. Later, when you’re looking for something, The Stack can help you find it.

There are three main mechanisms for this:

Ordering is one. Another of my theories is that a kind of locality of reference applies here. The things near the top of the stack, generally the things you added most recently, are often the things care about most.

For the few cases where this isn’t the case, I’ve added a mechanism for pulling older items back to the top. Note that this isn’t full re-ordering. You can’t move notes around in the list, you can just pull them to the top. This is a deliberate choice!

Tagging is another way to organise things. You can add #hashtags into notes, just like you do on your favourite social media site. You can then filter the stack by a tag. I find that this is all I need most of the time.

When I’m focussing on a task, I filter by the tag for that task, and I can see what I need to do next, in a list that isn’t too large. Periodically I will scan this list, and move items to the top if I think they are a priority.

For everything else, free text search lets you find notes that have fallen through the cracks.

Give It A Go

Anyway… that’s the idea behind the stack. I’m finding it useful, and will keep maintaining it for as long as I actually do. Your mileage may vary.

For now it’s free. I am hoping to use it as a vehicle to test some monetisation ideas based on true micropayments, in which case you might one day have to pay something for it, but if that ever happens, it will be a small amount derived from the real usage you make. Even then, the changes are that there will be an honour-based opt out.

If you’re interested in trying The Stack, download it from the app store on your phone or mac.

If you like it and would be interested in helping me test it, there’s also a public Testflight link.

Also, of course, The Stack exists as a place for me to experiment with new Apple technologies, and generally keep my skills up to date. One day it might also be a source of income, but for now, it’s free. ↩

App Storage

Thu, 30 Oct 2025 00:00:00 +0000

Whilst adding some settings to The Stack¹, I was reminded of something that has bugged me for a while about SwiftUI’s @AppStorage.

In a classic act of yak shaving, I decided to fix the annoyance instead of doing the task I actually set out to do…

Is That The DRY-Violation Klaxon I Hear?

SwiftUI’s @AppStorage macro is a neat way to access a UserDefaults value from within a SwiftUI view²

You use it like this:

struct ContentView: View {
    @AppStorage("username") var username: String = "Anonymous"

    var body: some View {
        VStack {
            Text("Welcome, \(username)!")

            Button("Log in") {
                username = "@samdeane"
            }
        }
    }
}

The ability to declare a default value is useful for the first time the user runs the app.

Unfortunately though, for most apps of a non-trivial size, you are likely to have some user-interface code in one place to allow the user to change the setting, and some other UI or application logic elsewhere that reads the value.

Which leaves you with something more like this:

struct SettingsView: View {
    @AppStorage("doTheThing") var doTheThing: String = true

    var body: some View {
        Toggle(isOn: $doTheThing) {
          Text("Show the button to do the thing?")
        }
    }
}

struct AppLogicView: View {
    @AppStorage("doTheThing") var doTheThing: String = false

    var body: some View {
      if doTheThing {
        Button("Do The Thing!) {
          performTheThing()
        }
      }
    }
}

Shome Mishtake Shurely?

Did you spot my deliberate mistake?

I set the default to true in one view, and false in the other.

My assumption is that what will actually happen here will depend on which view the user visits first, in the situation where they don’t already have a value set for the setting.

Which is… non-optimal.

It also bothers me that I have to type the "doTheThing" key in both places.

I might change it or get it wrong in one place and not the other.

I can even potentially use a different type for the same setting in different places.

A Better Way™

After thinking about this for a bit, I added the following extension³:

import SwiftUI

public struct AppStorageKey<Value> {
  let key: String
  let defaultValue: Value
  
  public init(_ key: StringLiteralType, defaultValue: Value) {
    self.key = key
    self.defaultValue = defaultValue
  }
  
}

public extension AppStorage {
  init(_ key: AppStorageKey<Value>, store: UserDefaults? = nil) where Value == Bool {
    self.init(wrappedValue: key.defaultValue, key.key, store: store)
  }
  
  init(_ key: AppStorageKey<Value>, store: UserDefaults? = nil) where Value == Int {
    self.init(wrappedValue: key.defaultValue, key.key, store: store)
  }
  
  init(_ key: AppStorageKey<Value>, store: UserDefaults? = nil) where Value == Double {
    self.init(wrappedValue: key.defaultValue, key.key, store: store)
  }
  
  init(_ key: AppStorageKey<Value>, store: UserDefaults? = nil) where Value == String {
    self.init(wrappedValue: key.defaultValue, key.key, store: store)
  }
  
  init(_ key: AppStorageKey<Value>, store: UserDefaults? = nil) where Value == URL {
    self.init(wrappedValue: key.defaultValue, key.key, store: store)
  }
  
  init(_ key: AppStorageKey<Value>, store: UserDefaults? = nil) where Value == Date {
    self.init(wrappedValue: key.defaultValue, key.key, store: store)
  }
  
  init(_ key: AppStorageKey<Value>, store: UserDefaults? = nil) where Value == Data {
    self.init(wrappedValue: key.defaultValue, key.key, store: store)
  }
}

I can use this in my application:

public extension AppStorageKey where Value == Bool {
  static let doTheThing = AppStorageKey("doTheThing", defaultValue: false)
}

struct SettingsView: View {
    @AppStorage(.doTheThing) var doTheThing

    var body: some View {
        Toggle(isOn: $doTheThing) {
          Text("Show the button to do the thing?")
        }
    }
}

struct AppLogicView: View {
    @AppStorage(.doTheThing) var doTheThing

    var body: some View {
      if doTheThing {
        Button("Do The Thing!) {
          performTheThing()
        }
      }
    }
}

These declarations can all live in different swift files (or even different packages).

I can define the settings key, type and default value once.

I get type inference everywhere that I use @AppStorage in this way, so I don’t have to declare a type.

As a bonus, when I type @AppStorage(. Xcode will auto-suggest any static AppStorageKey values that it knows about.

Which is nice…

I’m still looking for Test Flight testers for this. If you’d be up for giving it a go - even just to help me out by confirming that it doesn’t immediately explode, then please sign up. ↩
Or modifier, command, observable object, or various other SwiftUI structures. ↩
The repetition here with different types is ugly, but it mirrors the way that AppStorage defines its own API. It would be nice if there was a better way, but I’ve not found it yet. ↩

Caveat Emptor

Fri, 17 Oct 2025 00:00:00 +0000

I was looking back on some of my old blog posts from 2021 earlier¹, and I came across something that I thought bears repeating.

It was from this post, and the section I though was worth re-visiting was called “Caveat Emptor”.

It was about how my open source projects are often unfinished, and unpolished, and very much work in progress.

What I said then still applies today, and I’ll repeat it below.

As mentioned above, the context for the following is an old blog post, and so when it says “this post”, or “this project”, it’s talking about the original post.

Caveat Emptor

Part of the barrier to telling people about things I’ve done is sheer time it takes to write even quite a simple post like this one.

So my first disclaimer is just to say that this post is mostly a re-hash of the README file from the Github Repository. Nothing wrong with that I think, but just to be clear…

My second disclaimer is that this is work-in-progress code from the real world.

I’ve encountered a few people who subscribe to a fundamentalist view of open source code: that it’s useless unless it is fully polished, fully tested, 100% supported and actively maintained.

I understand this point of view; we’ve all encountered code that makes great claims and turns out to be broken or mostly unfinished.

Respectfully though, those people are wrong.

Imperfect open-source code can be frustrating. However, it can also be a helpful foundation for someone else to build on, a good example of the pros and cons of particular technique, or a useful supplier of that one crucial line you have been searching the internet for.

Aiming for perfection is setting the barrier way too high. I am as insecure as the next person when it comes to showing my workings in public. I’ve been a professional programmer for more than three decades, but I still suffer from impostor syndrome.

It’s tempting to hide away, but I’m trying to fight the urge, and I’d like to contribute in some small way to an environment where we aren’t scared to risk being wrong.

I offer up all of my open-source code in this spirit. It’s not perfect, because I am busy, and because I am still writing it. I find this code useful, and I hope someone else might. If you do find that it is fundamentally broken, please tell me why. That way I learn something.

Which sounds a little bit narcissistic now that I say it out loud. Ah well - bite me. I fell into a rabbit hole ok, and it just so happens to be one of my own making. ↩

Release Tools Tagging

Tue, 14 Oct 2025 00:00:00 +0000

After my last post, I thought a bit more about Release Tools, and decided that requiring a tag was definitely the right way to go, and over a couple of days last week I implemented it.

I also decided that it was a big enough change that I may as well call this Release Tools 4.0, and take the opportunity to clean up and remove some legacy code.

Tagging

Managing release tags in rt is now a separate step.

Running rt tag will examine the existing tags, and the HEAD commit.

If there’s a release tag already at HEAD, it will exit with an error.

If not, it will figure out the latest version number build number in use, by examining the existing tags.

It will then make a new tag using the same version, and with an incremented build.

This tag will be in the form: vX.Y.Z-NNNN where X.Y.Z is the semantic version, and NNNN is the build number.

Note that this does not include the -platform component that rt previously used.

From 4.0 forwards, we assume that there will be just one version tag for any given commit, and we will use that tag for all platforms.

We do however still support the old format when scanning previous tags – so rt will pick up any legacy tags and correctly calculate the new build number.

Archiving And Submitting

With 4.0, if you run rt archive or rt submit, the first thing that rt does is examine the HEAD commit, looking for a version tag in the format that rt tag creates.

If no tag is found, it will exit with an error. This ensures that any build you submit from a given commit will be tagged correctly, and that if you submit multiple platforms from the same commit, they are guaranteed to have the same build number.

Continuous Build Injection

If your project is set up to run the rt update-build every time you build, it would clearly be unworkable for it to require a version tag to exist at the HEAD commit.

If there is a tag at HEAD, rt update-build will use it.

Otherwise, it scans backwards to find the highest previous build tag, and then adds one to the build number.

In general I would discourage using rt for debug builds, since running a script for every build will slow Xcode down a bit, and having the build number available is of limited value.

However, the rt update-build command may still be useful if you have a custom build pipeline but want to use rt to calculate and/or inject build information.

Build Variables

Version 4.0 of rt also changes the names of the variables that are injected, and adds a new variable.

We now set the following variables in the .h, .xcconfig and .plist files:

RT_BUILD
RT_COMMIT
RT_VERSION

These three variables are also passed to xcodebuild on the command line.

If you were using rt already, you will need to adjust your project accordingly.

The rationale for the change was that it was probably better to use our own variables, rather than using CURRENT_PROJECT_VERSION which already has a meaning within Xcode.

That said, you probably will want to set CURRENT_PROJECT_VERSION to the value of RT_BUILD. You can do this in the build settings for the project, or each target, or by setting up an .xcconfig file which includes the line CURRENT_PROJECT_VERSION = $(RT_BUILD).

The semantic version that is injected is taken from the build tag that rt tag creates. By default it’s the same version that the previous tag had, but you can change it explicitly by doing rt tag --explicit-version <x.y.z>.

This allows you to make the git version tag the single-source-of-truth for all version information, if you so desire, and to inject the semantic version into all other settings and plists.

Legacy Cleanup

In rt 4.0, two commands have been removed.

The rt install command used to exist as a quick way of linking rt into your path. In general I think it’s better that you install rt with a tool such as Mint. However, some people will want to build from source, or do something else, and each installation method is likely to involve a different way to update $PATH. On the whole, this feels like it’s something that it out-of-scope for rt itself.

In the early days of rt, the design encouraged you to run it via some standard shell scripts, and also to include some standard .xcconfig files in every target. The rt bootstrap command existed to help you copy (or update) these scripts and config files into your project. This way of working with rt is obsolete, and so the command was a bit of an unnecessary legacy.

For the sake of simplicity, these two commands are no longer supported.

The fallback mechanism for calculating a build number by counting git commits has also been removed.

Development Notes

Doing these updates was another opportunity to experiment with AI code generation, and that’s what I did.

Rather than making the code changes myself, I largely tried to instruct Copilot to do them for me.

This was an interesting process.

The codebase is fairly mature, and a lot of what I was asking for involved refactoring existing code to add a little bit of new functionality. The results were mixed, and once again, it felt quite akin to working with an enthusiastic and willing colleague who had a bit less experience.

The first challenge was to express clearly what exactly it was I wanted. Much like test-driven development, I quite enjoy the fact that this forces you, early on, to work out what you actually do want. Also much like test-driven development, I didn’t always do a good job of working it out to begin with. Luckily, AI coding agents have infinite patience, and probably don’t bitch about you behind your back whilst having lunch with the other juniors¹.

In general the code that came back did work, and performed as intended. It was however often repetitious. The AI rarely showed insight about the codebase as a whole, and it had to be explicit prompted to clean up duplication and to create appropriate abstractions, methods, or constants in order to generalize. Again, this is quite like working with someone less experienced. They focus on the problem you’ve set them, and they stop when they think they’ve got it working. They don’t see the larger picture, and don’t consider consistency or maintainability of the codebase.

Part of this I think may be down to the fact that I had not set any general instructions in the project. I have now added a copilot-instructions.md file, and am experimenting with trying to set some standards in it.

One thing that I did like, and do think is useful, is that the AI generally created accompanying tests as a way of verifying each change I’d asked it to make. This is something that I aspire to, but don’t always manage, and having another “person” encourage me to work that way is excellent.

It also proved to be the right approach, in that it unearthed some problems; not just in the new code, but in some of the dependencies that I was using. These were subtle concurrency issues which mostly manifested when performing tests in parallel, and they may not have impacted actual normal usage of the tool², but that makes it all the more valuable that I was forced to confront them.

At the end of this process I did find myself wondering whether I could have achieved what I wanted faster if I’d just done it myself. I think that perhaps I could, and the code would have been tighter, for a narrow definition of “what I wanted”.

However, having an essentially tireless worker, who pro-actively volunteered to make tests, encouraged me overall to do a better job. Whilst getting Copilot to fix the duplication that it had created, I was also motivated to ask it to take a number of other refactoring steps aimed at improving consistency and making the code that I had previously written more idiomatic. Whilst tracking down the concurrency issues in the dependency I was using to run subprocesses (another of my projects, called Runner), I think I improved my general understanding of the surrounding issues, whilst also fixing some bugs I probably didn’t know I had in other projects using the same package.

Overall, I continue to be cautiously positive about using Copilot. I think that the problem domain of programming is a good one, especially when the output from the AI tool is small enough that it can be reviewed by a human expert who can provide feedback.

Asymmetry

I was talking to friend over the weekend about a situation where they were using AI to review large documents. This is a very different scenario, and the balance is completely reversed.

In my case, the AI tool is taking a vast amount of external knowledge and applying it to produce a small amount of new content, which is easily reviewed.

I don’t need to know where the ideas behind the solution came from, I just need to be able to read the new code and evaluate whether it works, and whether it fits in with the existing codebase.

This is quite asymmetrical, but in a direction that is positive.

In my friend’s case, the output from the AI was going to be a report, but the accuracy of that report could only be evaluated by essentially doing the same job that the AI had been asked to do.

From my own experience I’ve seen the AI make more than enough mistakes, and disappear down enough rabbit holes, that I would never trust its answers without being able to at least scan the output to verify it.

I wouldn’t want to use it to analyze or summarize a large body of information unless I had a pretty reliable way to validate the results.

Future

I continue to use rt for my own projects, and so I expect that it will evolve further over time.

One item on my to-do list is to try to add support for installing it via homebrew.

That’s not something I really need myself right now though, and so it may take me a while. Pull requests gratefully received…

This may be a wildly optimistic assumption. ↩
Most of the time. Maybe… ↩

Release Tools (Fastlane For Idiots)

Fri, 26 Sep 2025 00:00:00 +0000

My latest detour was to add an extra option to ReleaseTools, a command-line tool, written in Swift, that I made a few years ago.

Actually I’ve just checked, and I started it in 2019 🤯.

ReleaseTools (or rt for short) basically exists to automate the process of uploading an app to the app store, or packaging it up for external distribution via Sparkle.

I guess you could think of it as a bit like Fastlane, but without any of the bells and whistles¹.

It is yet another thing that I’ve never really got around to talking about! Largely because I made it for myself, and didn’t really want to end up supporting it for other people.

That said, it’s fairly mature now and I’ve used it in at least one client project as well as for a number of my own. Whilst I can’t guarantee that it will work for you, and I’m sure the documentation needs some improvement, I would certainly be happy to try to help someone else give it a go.

Scripting Like An Animal

Under the hood, rt uses xcodebuild, altool and git.

Prior to it existing, I was doing most of the same things that it does, using hand-rolled shell scripts for each project.

Or, in the case of my time working on Sketch, a big hairy load of Python I wrote²…

At some point I got annoyed with the fact that I was writing shell script, came to my senses, and decided that using Swift would be much more ~~efficient~~ fun.

Basic Design

If there was one thing I learned whilst hand-rolling all the previous bespoke solutions, it was that debugging build scripts is a massive pain in the arse.

Partly because debugging scripts is just generally painful, but also specifically because the build process tends to be slow, and it’s really annoying to have to keep waiting for a long task like archiving to run, only to have the subsequent exporting fail because you messed something up.

So when I made rt, I decided to try to factor it out into a series of small commands that were intended to be run in sequence.

Thus the basic design is that you can individually run commands to do things like:

archive
export from the archive
upload the export for distribution
upload the export for notarisation instead
wait for notarisation to finish
compress the notarised app
rebuild a sparkle feed to include the compressed app
publish the sparkle feed to your website

This lets you write a simple shell script³ to run the commands in sequence during normal operation, but when something goes wrong you can just re-run that command, and/or the subsequent ones.

Anyway, I won’t go into a lot more detail about the specifics - if you want those you can check out the README.

Suffice to say that it basically works these days, and I use it daily.

In fact I’ve added a fast path where you just run rt submit and it performs the archive, export and upload commands in sequence.

Build Numbers

One of the nice things rt does is calculate and inject a build number.

I prefer to do this, rather than relying on the app store portal to automatically assign one, as it lets me tag the exact commit that I built from in git. Once it knows that the upload has succeeded, rt makes a tag in git including the exact build number, version, and platform.

Originally, I calculated the number just using the count-the-git-commits trick.

This works surprisingly well most of the time, but it is a little fragile. In particular, if you switch branches, the count can change, and consequently the build number can go down. This is Not A Good Thing™.

In practice, I rarely encountered this problem. I commit little-and-often, and for projects I’m working on myself, I would probably only submit from a single branch.

However, when I working on Club, we did have this problem. That project didn’t use rt at all - it was cross-platform, and written in Dart/Flutter, with an entirely different toolchain. It started out doing the commit-counting, but we ended up switching to a solution that explicitly read the existing git tags and used them to work out the next build number.

When I subsequently came back to my own projects, I was inspired by the tag-based approach and decided that rt should use it too.

Version Tags

So I added an option to rt which calculated the new build number by:

scanning for tags in the form vX.Y.Z-platform-NNN, eg v1.0.2-iOS-234.
treating the highest existing NNN for our platform as the current number
adding 1 to it for the new number

That works really well, and because rt also creates and pushes a tag in the same format, it’s pretty reliable.

The only wrinkle with it is that when you are supporting two or more platforms, you have to submit each one with rt separately, e.g:

rt submit --platform=iOS
rt submit --platform=macOS

Sometimes a problem will occur, or something will get broken, such that one upload succeeds and the other fails.

This becomes a problem subsequently because you’ve now got one platform with a tag that worked, and which the app store knows to have that build number, but another platform that only has an older tag.

So when you subsequently upload the next build, you end up with different build numbers for each platform, even though they are built from the same commit. Which is confusing and a bit annoying.

Why Are You Telling Me All Of This Again?

Good question.

Come to think of it, the main point of this whole post - other than just answering, in a rambling way, the “how was your day dear?” that you didn’t ask - was to mention the existence of rt.

Which I’ve done.

You can stop reading now!

What follows is more detail than you probably want to know about why I started actually working on rt recently, what I did to try to fix the tagging problem, and why I’ve realised that I need to go back to my fix!

Inconsistent Tags

To fix the inconsistent tags manually, the easiest thing to do has been to use git on the command line to make a tag with the right build number, for the platform that had fallen behind, on the commit that it should have been uploaded from.

That way, rt will find the tag next time, add 1 to it, and come up with the right value.

This is a bit clunky. Also, occasionally, I only want to release one platform, as I may have changed code that just affects it. Next time I submit though, I want to release both platforms using the highest build number for any platform.

So I decided to try to add some new capabilities to support this objective.

First, I’ve added an --explicit-build option to allow you to specify the build number to use. That is a cleaner way to reset everything when doing a new upload, as you can just force the number for both platforms to get them back in sync.

I’ve also added an --existing-tag option. This looks for the highest tag for any platform, as well as for the platform you’re uploading, and compares the two. If there’s a higher number for another platform, it will use that. If not, it will do what it used to do and increment the previous build number by one.

This works nicely for the situation where a build or upload failed for one platform in a transient way, you’ve fixed it with some minor commit, and you just want to upload something with the same number as the other platform(s).

I actually thought that I was done, but whilst writing this blog post, I’ve realised that I’m not.

If the commit has changed, you really should use a higher build number - but it needs to be higher than any platform has used, and not just higher than the platform you’re uploading.

I think posibly what rt needs to do is to figure out whether the tag from the other platform is on the HEAD commit. If it is, then what you’re doing is “catching up” and it should just use the same build number - it’s the same commit, so using the same number makes sense.

If there’s no version tag on HEAD though, then we probably want to increment the highest number by one more, and use that. This will create a new baseline with the first platform that you upload, and subsequent platforms will then catch up to it.

So I guess that’s the next job then…

Or…

… although, maybe the problem here is that the design is wrong.

The basic problem is that when making the tag, rt doesn’t know which platforms you’re uploading, as it does them one at a time.

I can see a couple of ways to fix this.

One would be a way to pass a list of platforms in, and have them all upload at once.

Another… which I am coming round to instead… is making the tag creation an explicit and separate step.

This feels more in keeping with the small-individual-commands design.

Maybe version tags should not be platform-specific, and just in the form vX.Y.Z-NNN.

If you run rt submit or rt archive and there isn’t a version tag on HEAD, it should just refuse to do anything.

Then we can have a separate rt tag command which makes a new version tag. So you run that first, then run the archive or submit commands for each platform in turn.

We can still have a small shell script that you can run for the normal situation where you want to upload everything at once:

rt tag
rt submit --platform=iOS
rt submit --platform=macOS

You can still run the individual bits though, and they will do the right thing. If you’re on a tagged commit they will work. If not, they won’t. If you run rt tag on a commit that’s already tagged, it can spot that and complain.

This feels a lot cleaner actually.

I’m glad we had this talk.

Thanks for listening!

No offence to Fastlane, but I’ve always found it to be complicated and confusing, and the dependency on Ruby annoys me. ↩
To be fair, these scripts did a whole load of other stuff too. They were a bit hairy though… ↩
Yes we’re back to shell scripts. Teeny tiny ones though. Honest. ↩

Dipping A Toe Into The AI Waters

Tue, 23 Sep 2025 00:00:00 +0000

Ok, I admit it, I’ve been tinkering with AI again.

Not using it, this time, but trying to add it to my app The Stack.

Yet another person shamelessly trying to shoe-horn some AI into their app, so that they can jump on the bandwagon?

Well yeah, guilty as charged, I guess. Anyhoo…

Summarising Notes

Individual notes in the stack are generally quite short. Things like “add a blog post talking about adding AI to The Stack”. There’s probably not a lot of mileage in summarising them.

Given a long list of them though, it’s easy to get swamped.

Could we use some sort of AI to generate a summary of all items, or of all items with a given tag? Maybe it could pull out one or two emerging themes? Perhaps also suggest the item to tackle next?

On-Device

For iOS and macOS 26.0, Apple offer a new on-device Foundation Model.

This seems like it’s tailor made for my use case.

The query doesn’t leave your device, so there are no privacy issues to contend with.

So I decided to give it a go.

Adding The Code

On the plus side, adding the code for this was ridiculously easy. About three lines of actual Swift:

  model = LanguageModelSession(instructions: summarizerInstructions)
  let response = try await model.respond(to: prompt)
  return response.content.trimmingCharacters(in: .whitespacesAndNewlines)

It’s no exageration to say that the instructions and prompt that I feed to the AI is a lot longer than the code I use to invoke it.

Therein lies one problem, however. The prompt. Getting a prompt that actually produces useful output is difficult.

I’m initialising the model with these instructions:

    let summarizerInstructions = """
      You summarize a list of to‑do notes for planning.

      Rules:
      - Output: one concise paragraph, no more than 50 words
      - Use plain text, no headings or lists.
      - Weigh recently updated items slightly more, but consider all items.
      - Use tags only as background context; never mention tag names in the output.
      - Prefer synthesis over enumeration; use actionable, neutral language.
      - Summarise for the current user only. Do not refer to teams or other users.
      - Write in the imperative mood where possible. Do not address the user directly.
      - Do not invent notes or details.
      - Write in the same language as the notes.
      """

Then giving it the following prompt:

  var prompt = """
      Summarize the following to‑do items into a single paragraph that captures the main themes and priorities.

      Each item is in the form <date>: <body>, where: 
      - <date> is the date that the note was last modified (more recent = higher weight)
      - <body> is the note body, including any hashtags

      Items:
      \(summarisedItems.joined(separator: "\n\n"))
      """

This took quite a lot of tweaking. Inevitably, I asked Copilot to help 😆.

I am sure it could be greatly improved.

So Far, So Meh…

The current prototype sometimes does a decent job, but the output has a tendency to end up a bit wordy.

I haven’t had it completely hallucinate, but it does sometimes completely ignores parts of its instructions!

I understand enough about the process to not be surprised by this, but the level of unpredicability makes it quite difficult to rely on.

Worse, I’m not entirely sure that the output is particularly helpful!

More testing required I think, particular with large lists of items.

There’s a bigger problem with that, however, when using the on-device model.

Unfortunately the context window is small. It only supports 4096 tokens, where each token is a few characters of text.

Even with a modest collection of a couple of hundred notes, it’s easy to exceed that window, resulting in an error.

I suspect that this means that the on-device approach is a non starter, and it will be necessary to send the entire item list to an online model. Which opens up a whole other can of worms…

Oh well.

Conclusion

Interesting experiment.

I’m not yet convinced, but will keep playing…

Elegant Chaos

Fixing The ActionBuilder Plugin

The Deadlock

Unexpected Lack Of Items In The Bagging Area…

Smoke Em If You Got Em

Other Fixes In Passing

Localizable String Catalogues in Swift Packages

Lots Of Small Targets

Using Catalogues In Packages

Which Catalogue Was It Again?

Building Outside Xcode

Other Possible Patterns

SwiftUI Navigation Pain

Actions

SwiftUI Navigation vs Actions

Watching The Path

Not Using NavigationPath

Imperfect Solutions

Tune In Next Time…

Am I Holding It Wrong?

All Quiet In The Western Isles

The Stack

Isn’t This A Solved Problem?

The Stack Isn’t Reminders

The Stack Isn’t A Methodology

The Stack Isn’t An Issue Tracker

So What’s Left?

Triage?

A Big Heap ‘O Stuff

Give It A Go

App Storage

Is That The DRY-Violation Klaxon I Hear?

Shome Mishtake Shurely?

A Better Way™

Caveat Emptor

Caveat Emptor

Release Tools Tagging

Tagging

Archiving And Submitting

Continuous Build Injection

Build Variables

Legacy Cleanup

Development Notes

Asymmetry

Future

Release Tools (Fastlane For Idiots)

Scripting Like An Animal

Basic Design

Build Numbers

Version Tags

Why Are You Telling Me All Of This Again?

Inconsistent Tags

Or…

Dipping A Toe Into The AI Waters

Summarising Notes

On-Device

Adding The Code

So Far, So Meh…

Conclusion

Not Using `NavigationPath`