SHIINAYANE (en)

I Turned My AI Workflow into Code. Then I Tore It Apart.

Mon, 27 Jul 2026 00:00:00 GMT

On July 25, I published I Turned My AI Workflow into Code.

One day later, I tore apart its central premise.

The timing was almost funny. When I finished that post, I thought the engineering workflow BiliKit had forced me to develop was finally becoming stable: risk levels, quality gates, independent review, complexity budgets, and eventually a pair of reusable Codex Skills.

The next day, BiliKit itself gave me a counterexample.

The scroll position that kept getting more complete

I was working on M5.0. The requirement sounded simple:

Open a video from a browsing page, return from playback, and see roughly the same part of the page as before.

BiliKit was using a custom routing model. Opening playback removed the browsing view from the tree. Returning created it again, which meant its content and scroll position had to be restored manually.

The first version remembered the selected video ID. That could bring the card back on screen, but it could not restore the viewport I had actually left.

So I started storing a raw offset.

Every problem that followed was reasonable:

The old offset might become unreachable after the content height changed.
A callback from the old ScrollView could contaminate a new snapshot.
Late asynchronous results needed request identity and generation checks.
User scrolling had to release the programmatic restoration state.
Deterministic tests and XCUI had to prove that returning really looked like leaving.

Each fix made the implementation more complete.

It passed the tests too.

That was the troublesome part. Tests, reviews, and gates were all checking whether the restoration mechanism was correct. Nobody kept asking:

Why does the browsing page have to be destroyed at all?

I eventually stopped and built a small SwiftUI probe comparing conditional replacement, explicit restoration, and a native NavigationStack.

The result was direct.

With NavigationStack, the root view was not created again and its state identity survived. A substantial part of the restoration problem came from the navigation structure we had chosen ourselves.

BiliKit then moved to a native TabView(.sidebarAdaptable), with a separate NavigationStack(path:) for each tab. The custom AppRoute and AppReturnSnapshot went away. Bounded browsing worksets stayed, along with request cancellation and playback lifecycle handling. SwiftUI now owns the scroll position through semantic IDs.

Two real popular-feed round trips measured:

0.195066 → 0.194867
0.389877 → 0.389447

There was no longer a reason for the ViewModel to store a raw numerical offset and own the clamping, restoration latch, and stale callback isolation around it.

The process worked exactly as designed

No agent was obviously slacking off here.

The repository rules were read. The risks were identified. The validation level was reasonable. The implementation work found real bugs involving stale callbacks, unreachable offsets, lifecycle cleanup, and XCUI driving.

Every part of the process had accepted the same premise: keep the existing navigation structure and make state restoration reliable.

Once that premise entered the task contract, the agents became very good at following it.

Reviewers checked boundaries. The red reviewer searched for failure paths. Tests accumulated, and the documents became more complete. Every layer improved the correctness of the current approach while making it look more like the only approach worth continuing.

In the previous post, I described project-governance-bootstrap as a small compiler:

repository facts
+ architecture documents
+ tests
+ security boundaries
→ project rules

There is a large problem with that analogy.

A compiler can only process what it receives.

If the architecture, task contract, and current implementation all omit a simpler route, the Skill can only compile the existing route more strictly. Path dependence does not disappear. It gets organized into better documents, more checks, and stronger momentum.

I nearly turned the correction into another process

My first reaction was still to turn this experience into rules.

Perhaps every high-risk task should list alternatives first. Perhaps it needed a mandatory challenger, a decision ledger, and another reviewer dedicated to checking the problem definition.

It started feeling wrong while I was writing it.

I was adding process to prevent too much process. To keep agents from mechanically following a task contract, I was preparing a longer task contract.

That was not far from what I had just torn apart.

So I did not make a workflow v2.

I simplified BiliKit's collaboration rules directly. One commit removed 766 lines of configuration and documentation, along with five fixed agent definitions. The current AGENTS.md keeps project facts, architectural boundaries, safety constraints, working validation commands, and commit conventions.

The quality checks are still there.

SwiftPM, xcodebuild, lifecycle tests, and security boundary checks still answer useful questions: whether the build broke, cancellation is correct, resources are released, and the real app can run.

Fixed risk colors, task-contract forms, reviewer chains, and complexity budgets are no longer default ceremonies.

They remain available when a change actually needs them. Every task no longer has to prove that it followed the process.

What happens to the two Skills?

apple-dev-loop is mostly fine for now.

It routes Apple-platform validation: when SwiftPM is enough, when xcodebuild is needed, and when evidence requires an .xcresult, a signed app, XCUI, or Instruments.

The boundaries of that job are fairly clear.

project-governance-bootstrap is different.

It was designed to derive governance from a repository. That carries an assumption that enough repository context can produce the right workflow for the project.

BiliKit just demonstrated that a repository can describe the wrong route in great detail.

I am going to reconsider that Skill. It may shrink into a tool that only collects existing facts and validation entry points. I may archive it instead. I have not decided yet.

No new answer yet

The main BiliKit source and test directories now contain almost 25,800 lines of Swift.

The project is still too large for one prompt followed by one diff review. The old rules were not useless either. They caught plenty of real problems.

I no longer think I can turn that experience into a universal workflow and have it choose the right route for the next project.

At least it could not this time.

I am keeping the July 25 post. It records something I genuinely believed at the time. Quietly rewriting or deleting it would make the story less useful.

This post records what happened the next day.

I will decide what comes after that when the project forces me to change again.

I Turned My AI Workflow into Code

Sat, 25 Jul 2026 00:00:00 GMT

Update, July 27, 2026: The day after publishing this post, BiliKit M5.0 exposed the biggest problem with this workflow: it could make a chosen route increasingly rigorous without ever checking whether the problem should be solved that way. I am leaving the original post intact and wrote a follow-up: I Turned My AI Workflow into Code. Then I Tore It Apart.

BiliKit V1 is not finished yet, and the Swift codebase has already passed 21,000 lines.

When the project was small, my AI workflow was straightforward: write a longer prompt, let the agent make the change, and check the diff myself. Even when it got something wrong, the change usually touched few enough files that I could spot it quickly.

That stopped being enough as the repository grew.

The same instruction—"read the project rules before making changes"—could produce very different results in a new session. Sometimes every test passed, but the change landed in the wrong module. Sometimes a small fix came back with an entirely new abstraction.

BiliKit also has several areas that a green test suite cannot fully cover: Keychain access, playback lifecycles, cancellation, danmaku rendering, and the local server. A successful build does not tell me whether those paths work in a signed app or survive actual use.

So the repository gradually accumulated more machinery:

AGENTS.md
risk levels
quality gates
independent review
complexity budgets
different validation paths for different kinds of work

After a while, the workflow was reasonably stable inside BiliKit. Then I started another project and realized I would have to assemble it all over again.

Some rules lived in AGENTS.md, some in gate documents and scripts, and some were still habits in my head. I could rewrite them from memory or copy the BiliKit files.

The first option would miss things. The second would bring far too much baggage.

A static website does not need BiliKit's rules for playback, Keychain, local servers, or media redirects. A utility with fewer than 1,000 lines may still need strict handling if those lines touch credentials.

What I wanted to reuse was the way those rules were derived.

I created a repository called codex-engineering-skills and started with two Codex Skills:

project-governance-bootstrap
apple-dev-loop

The first reads a project and builds engineering rules that fit it. The second handles the build, test, and validation loop for Apple-platform work.

Copying BiliKit's AGENTS.md did not work

My first idea was to turn BiliKit's AGENTS.md into a generic template.

It did not take long to find the problem.

BiliKit treats authentication, redirects, local servers, playback, concurrency, renderers, and destructive migration as high-risk work. That list makes sense because the project actually has those failure modes. Put the same list in a static website and it becomes ceremony. Ask a command-line parser to validate Keychain behavior in a signed app and the workflow becomes ridiculous.

project-governance-bootstrap therefore starts by reading the repository:

existing instructions
architecture decisions
manifests and dependencies
tests
CI
security boundaries
release process

It then chooses one of three rough profiles:

light: small, easy to roll back, and mainly one validation path;
standard: multiple modules, public boundaries, persistence, CI, or several test layers;
critical: credentials, authorization, destructive migration, untrusted input, local servers, media lifecycles, or production infrastructure.

Line count is only a clue. One hundred thousand lines of generated code may be harmless; a short migration that deletes data is not.

The result is still the project's own policy. The reusable part is the process used to produce it.

It ended up looking more like a compiler

I now think of project-governance-bootstrap as a small compiler.

Its input looks roughly like this:

code
+ manifests
+ architecture documents
+ tests
+ CI
+ security boundaries
+ release rules

Its output looks like this:

source-of-truth order
+ architectural boundaries
+ risk areas
+ validation entry points
+ authorization limits
+ optional reviewer roles

There are templates in the repository, but they are only starting points. If a section does not apply, it should disappear.

Templates have a habit of keeping themselves alive. Once a generic "Security" section exists, both people and AI tend to fill it with text even when the project has no meaningful security boundary. The document becomes complete-looking and mostly useless.

If the repository already has a command that proves the relevant result, there is no reason to add another gate script. If there is no special security boundary, a few paragraphs of generic security advice do not help.

Enough is enough.

Why there are two Skills

The original BiliKit workflow mixed two questions:

What does this repository require?
How should this Apple-platform change be validated?

They often appear together in BiliKit, but I split them when making the workflow reusable.

project-governance-bootstrap owns the repository rules. It may decide that a project needs signed-app evidence, UI testing, or a performance recording, but it does not contain every Xcode procedure.

apple-dev-loop owns the actual validation. It knows when to use SwiftPM, xcodebuild, .xcresult, XCUI, a signed app, Computer Use, or Instruments. It does not decide the application's architecture or risk policy.

They can be used together, but neither depends on the other. The governance Skill can also work on Rust, TypeScript, or documentation repositories. The Apple Skill can work in a Swift project that already has its own engineering rules.

A Skill also needs to know when to stay out

While writing the Skills, I found that the trigger description needed as much care as the workflow itself.

If apple-dev-loop ran whenever a request mentioned Swift, a syntax question could suddenly turn into Xcode preflight, scheme discovery, and a full build. Thorough, perhaps, but also completely unnecessary.

Its trigger therefore says when the full loop applies and when it does not. It is useful when a task really needs the Apple toolchain, signing, a device, UI validation, or performance evidence. A source-only Swift explanation or a narrow package edit usually does not.

project-governance-bootstrap has a similar boundary. The existence of an AGENTS.md file is not, by itself, a request to redesign the repository's governance.

I used to think extra instructions were mostly harmless. In practice, they consume context and change tool choices. Detailed Instruments instructions make Instruments look tempting even in a simple package-test task.

More context can create more work.

Keeping SKILL.md small

The first design almost became two enormous SKILL.md files.

The governance Skill would have contained every risk category, template, reviewer role, and Apple exception. The Apple Skill would have contained every Xcode, XCTest, signing, simulator, UI, and Instruments recipe.

Now each Skill keeps a short core workflow and reads supporting material only when it is needed.

An ordinary repository never loads the Apple profile. A task that does not need independent roles never loads the agent-routing guide. A package test does not load Instruments instructions in advance.

This is usually called progressive disclosure. I think of it as dependency management for context.

The details of a tool make it more likely to be selected. Loading less is useful when the omitted material cannot help with the current decision anyway.

How far should Apple validation go?

apple-dev-loop uses an evidence ladder:

source inspection and static constraints
SwiftPM, unit, and integration tests
xcodebuild with a structured .xcresult
Xcode-aware diagnostics and actions
deterministic XCUI tests
a signed app and real UI interaction
targeted xctrace or Instruments recording
CI, device matrices, and independent review

The point is not to reach the last step every time. It should stop at the first level that can prove the current claim.

A screenshot cannot replace a unit test. An unsigned build cannot prove Keychain access. Launching the app does not prove a lifetime issue is fixed. A trace from one Mac does not represent every supported device.

The Skill also includes a few small scripts. One records the repository, workspace, scheme, Xcode, and Developer Directory before an expensive run. Another reads structured results from .xcresult instead of guessing from thousands of lines of console output.

I did not try to rebuild Xcode in shell. The scripts only cover bounded steps where automation removes ambiguity.

Even the installer needs guardrails

The repository has a script that installs the Skills as symbolic links so Codex can discover them.

If the destination already points to the correct location, the script does nothing. If it is another link or a real directory, the script refuses to overwrite it.

It is a small detail, but an installer that silently replaces an existing Skill is an easy way to lose data. The same applies to changing global xcode-select just to make one build pass: it may fix the current project and leave every other Xcode project with a surprise.

The Skills prefer configuration scoped to the current task. Ambiguous state causes a stop, and a missing optional tool is only a blocker when the current claim actually requires it.

Vague rules became harder to keep

Inside BiliKit, a sentence such as this felt clear enough:

Important changes require independent review.

In a reusable Skill, it immediately raises more questions. What counts as important? Does every multi-file edit need review? What should the reviewer know? What happens when two reviews disagree?

The rule had to become narrower.

Green work does not need a review ceremony. Non-mechanical yellow work may get an independent read-only review. Red work focuses review on failure paths, cancellation, ownership, security, cleanup, and rollback. It also gets a complexity budget, because "being rigorous" can otherwise keep adding process forever.

Other familiar instructions had the same problem.

"Run the full test suite" is wrong when the highest deterministic mode already includes the lower modes. "Test on a real device" only makes sense when deterministic tests cannot prove the claim. "Use Xcode MCP" still requires checking which Xcode process, window, workspace, and scheme it is connected to.

Rules that survived through project context needed explicit conditions once they became reusable.

The Skills need tests too

The repository has a validator for metadata, internal links, unresolved placeholders, shell syntax, and formatting. The link installer has separate conflict checks.

Those checks only prove that the files are structurally valid.

A Skill can have clean metadata and valid shell while still making poor decisions. It can trigger too broadly, produce rules that are too heavy, ignore existing project constraints, or recommend evidence that does not answer the question.

The useful test is trying it from a fresh context on different repositories.

For project-governance-bootstrap, I want to try a small reversible tool, a normal multi-module application, and a project with real security or lifecycle risk. The generated rules should be different.

For apple-dev-loop, I want to see whether it stops in the right place: package tests for a package change, xcodebuild for an Xcode project, a signed app for Keychain, and Instruments only for an actual performance question.

If the result is still BiliKit's rules with the project name replaced, I will have to go back and change it.

AI Made Code Cheap. It Made Engineering More Expensive.

Fri, 24 Jul 2026 00:00:00 GMT

BiliKit has not reached version 1 yet, but it already contains 21,300 lines of Swift.

That number includes about 12,700 lines of production code and 8,400 lines of tests across 125 Swift files. The app can browse and search Bilibili, log in through a web QR flow, play DASH video with AVPlayer, show subtitles, schedule danmaku on the playback timeline, and keep the renderer running under sustained load.

It still needs a proper UI pass, more Mac-specific work, signing, notarization, release engineering, and the final v1 regression matrix.

This is also the first project where my original AI workflow stopped being enough.

In the beginning, I would describe a feature, let the model inspect the repository, ask it to implement the change, run the tests, and then read the diff. This worked quite well while the repository was small. Even when the model put something in the wrong place, the change was usually small enough to understand and repair.

As BiliKit grew, the failures became harder to spot.

The code usually compiled

The annoying part was that AI rarely failed by producing obviously broken Swift.

Playback alone crosses networking, HTTP byte ranges, SIDX parsing, generated HLS playlists, a loopback HTTP server, AVPlayer lifecycle, cancellation, seeking, and CDN fallback. Authentication involves a remote state machine, ephemeral URL sessions, redirect policy, Keychain storage, request authorization, logout cleanup, and UI state. Danmaku goes through protobuf decoding, segment prefetch, deduplication, a shared media timeline, lane allocation, Core Animation, and object lifetime.

A change could look perfectly reasonable inside one file and still be wrong for the whole path.

Some actual failure modes were:

a type living in the most convenient module instead of the module that owned its meaning;
a test passing because one Task.yield() happened to be enough on that run;
cancellation stopping the UI update while leaving the underlying resource alive;
an anonymous media request inheriting authenticated headers;
a benchmark harness growing into a small framework before answering the original question;
a document describing a planned capability as if it already existed.

Most of these survive a quick diff review. Some even survive the full test suite.

My first reaction was to write longer prompts. That helped for a while, but every new conversation needed the same background again: product scope, architecture, old decisions, risky areas, and how to verify the change. Important details were mixed with whatever I happened to be working on that day.

At some point, adding more text to the prompt became a pretty bad way to maintain the project.

Moving the context into the repository

BiliKit gradually accumulated a roadmap, Architecture Decision Records, threat models, dated validation records, and an engineering guide.

These files do different jobs.

The current code and build configuration describe what exists now. Accepted decisions record boundaries that should not be reopened casually. The roadmap separates current work from later ideas. Validation records preserve what happened in a particular environment, including results that may become outdated.

This distinction matters because the project has plenty of attractive distractions. Downloads, transcoding, live streaming, multiple accounts, and region unlocking can all produce a convincing implementation plan in a few minutes. They are still outside the v1 scope.

I also started writing a small contract before non-trivial changes:

Goal: the observable behavior that should change;
Context: relevant entry points, decisions, and known limitations;
Constraints: dependency direction, security, cancellation, lifetime, and scope;
Done when: the test, probe, measurement, or visible behavior that closes the task.

If I cannot describe the goal in one sentence, the task is usually carrying more than one change. If “done when” only says that tests pass, I probably have not identified the risky behavior yet.

This made new conversations much easier to start. They no longer needed the entire history of the previous conversation. They could read the contract and the files that already belonged to the project.

Building one real path at a time

AI is very good at filling an empty architecture.

It can generate all domain models, all repository protocols, all use cases, and all views in one pass. The result often looks impressively organized. It may also contain protocols with no real caller, placeholder targets, and abstractions based on features that do not exist.

BiliKit now prefers vertical slices.

The architecture is still layered:

Scene → View → ViewModel → Use Case → Repository Port → Adapter

Implementation moves through those layers for one observable behavior.

Authentication started with the QR state, credential ownership, one authorized endpoint, one UI flow, restart recovery, and logout. Danmaku started with one media timeline, one segment contract, bounded scheduling, and then a renderer connected through the real playback chain.

This is slower than asking AI to scaffold an entire subsystem in one shot, but there is much less empty code to clean up later.

Five changed lines can still be red

I used to associate a small diff with a small risk. BiliKit cured me of that fairly quickly.

Five lines in redirect handling can expose credentials. A small task-ownership change can introduce a leak or stale-result race. A short persistence migration can destroy user data. Meanwhile, a large generated protobuf file can be almost entirely mechanical.

The repository now classifies work by failure mode:

Green: local presentation changes and narrow mechanical edits;
Yellow: ordinary features, use cases, cross-file refactors, and public APIs;
Red: authentication, Keychain, media, redirects, local servers, concurrency, resource lifetime, renderers, migrations, deletion, and irreversible changes.

Green work gets the baseline checks and a focused diff review. Yellow work gets a written contract and usually a fresh read-only review. Red work needs a decision gate, a bounded experiment when the route is uncertain, measurements that match the risk, and explicit approval before a risky experiment becomes production code.

The classification actually reduced the amount of process. A CSS change does not need the same ceremony as Keychain or AVPlayer lifecycle work.

I also started giving uncertain experiments a complexity budget. A renderer comparison does not need ten candidates, five output formats, and a reusable benchmark framework. It needs enough candidates and measurements to answer the product question.

The danmaku renderer was developed this way. The comparison lived on a non-mergeable spike branch and used synthetic load to choose a route. Once it had answered that question, production implementation started separately. The benchmark did not get promoted just because it already worked.

Tests only prove what they observe

One subtitle test taught me this in a very direct way.

The test called Task.yield() once and assumed the asynchronous stream would publish observable state. It usually passed. The race appeared only when the unified project gate ran under a different timing profile.

Rerunning it until green would have hidden the problem again. The test had to wait for the state it actually cared about.

BiliKit now has one reproducible entry point for static checks, package tests, and the full app build. Risky paths add their own evidence:

deterministic fixtures for protocol behavior;
negative tests for source and redirect policy;
a signed smoke test for Keychain;
real AVPlayer probes for playback;
controlled high-density runs for danmaku;
longer measurements for memory and cleanup;
manual checks for UI behavior that automation cannot judge usefully.

An unsigned build cannot prove that Keychain works. A screenshot cannot prove cancellation. A successful launch says very little about a renderer after 30 minutes.

Running every available tool is also pointless. A Swift Package change may be finished after package tests. Instruments belongs to an actual performance question.

The workflow I ended up with

For ordinary BiliKit work, the loop now looks roughly like this:

Read the current code, roadmap, relevant decisions, and tests.
Write one observable goal and decide what would prove it.
Classify the task by the cost of failure.
Set a complexity budget if the implementation route is uncertain.
Build the smallest vertical slice.
Use a fresh, read-only context for meaningful reviews.
Run the shared automated gate.
Add the environment-specific evidence required by that change.
Update current documentation without rewriting old validation history.

This would be ridiculous for a weekend script. BiliKit has authentication, playback, a local server, concurrent state, and a renderer, so the simple prompt-and-review loop stopped scaling much earlier than I expected.

The project is still before v1. The workflow will probably change again before release.

For now, at least, a new conversation no longer has to remember the whole project by itself.

I later extracted part of this workflow into reusable Codex Skills. The follow-up, I Turned My AI Workflow into Code, covers that process.

What's New in Swift — WWDC26 Notes

Thu, 11 Jun 2026 00:00:00 GMT

I watched this year's What's New in Swift session and wrote down the parts I will probably need later. Becca and Evan covered Swift 6.3 and 6.4, with quite a lot packed into one session: small syntax changes, library additions, Android and Wasm, and more ownership work.

This is a reference note, so I have kept the examples instead of trying to turn everything into one big takeaway.

Everyday Swift

Optional parentheses around `some` and `any`

An optional some or any type no longer needs another pair of parentheses:

// Before
func delegate() -> (any Renderer)?

// After
func delegate() -> any Renderer?

Small change, but definitely easier to read.

`weak let`

A weak reference previously had to be a var. That was awkward for Sendable types and sometimes led to @unchecked Sendable just to get around it.

Swift 6.4 allows immutable weak references to use weak let, so this case can express real Sendable conformance without the escape hatch.

`~Sendable`

~Sendable explicitly marks a type as non-Sendable without preventing its subclasses from becoming Sendable.

Task errors now get a warning

Ignoring an error thrown from a Task now produces a warning. Silently losing an error from an unstructured task is very easy to miss, so I am glad the compiler finally points it out.

Async work in `defer`

An async function can now be called from a defer block.

Two memberwise initializers

For a struct containing both internal and private stored properties, Swift can synthesize two memberwise initializers at the corresponding access levels. There is no need to write one manually just because the properties have mixed visibility.

`@diagnose`

@diagnose controls one diagnostic on one declaration:

@diagnose(DeprecatedDeclaration, as: ignored, reason: "Flying with surplus hardware")
func makeApolloSoyuzMission() -> Mission { ... }

@diagnose(StrictMemorySafety, as: warning)
func uplinkCommand(from receiver: inout Receiver, to computer: inout Computer) { ... }

@diagnose(ErrorInFutureSwiftVersion, as: error)
func fetchPosition() -> (x: Double, y: Double, z: Double) { ... }

This is probably my favorite small addition in the session. A special call site no longer requires changing the warning level for the whole project, and reason: leaves an explanation next to the exception.

Module selectors with `::`

Swift 6.3 added :: for resolving symbols with the same name in different modules:

import Rocket
import GiftShopToys

let r1 = SaturnV()          // ambiguous
let r2 = Rocket::SaturnV()  // the type from Rocket

It also works on members. For example, technician.HumanResources::fire() selects the member from a particular module.

Library updates

Standard library

withTaskCancellationShield { ... } runs a critical section even when the surrounding task is cancelled. The session uses sending a final SOS packet as an example.

Dictionary.mapKeyedValues transforms values while also giving the closure access to each key:

missions.mapKeyedValues { mission, window in
    makeDisplayName(for: mission, in: window)
}

FilePath is a cross-platform path type with structured components:

var path: FilePath = "/var/www/static"
path.components.append("WWDC")
// [ "var", "www", "static", "WWDC" ]

Swift Testing

Issue.record(..., severity: .warning) records a warning without failing the test.
try Test.cancel("reason") stops a parameterized case when it does not apply.
swift test can repeat a test until it passes or fails, with a configurable maximum. This should be useful when tracking down a flaky test.
#expect now works inside XCTestCase, while XCTest assertion failures appear as Swift Testing issues. Existing XCTest suites can therefore migrate gradually.

Subprocess 1.0

The Subprocess package reached 1.0. It has a cleaner API, improved error handling, and cross-platform line-by-line output streaming:

let result = try await Subprocess.run(
    .name("ls"),
    input: .none,
    output: .sequence,
    error: .string(limit: 4096)
) { execution in
    execution.standardOutput.strings().filter { $0.hasSuffix(".obj") }
}

The package handles differences such as platform file descriptors and termination statuses.

Foundation `ProgressManager`

ProgressManager is a new progress API designed for async/await. A parent assigns part of its total with subprogress(assigningCount:); the child reports its own local stages without needing to know the parent's total:

let manager = ProgressManager(totalCount: 100)
try await rocket.launch(manager.subprogress(assigningCount: 100))

extension Rocket {
    func launch(_ progress: consuming Subprogress? = nil) async throws {
        let stage = progress?.start(totalCount: 3)
        try await ignite();          stage?.complete(count: 1)
        try await liftoff();         stage?.complete(count: 1)
        try await stageSeparation(); stage?.complete(count: 1)
    }
}

Foundation's move to pure Swift also continues. The session mentions faster Data operations and bridging, plus one unified Swift implementation behind NSURL and CFURL.

Swift outside Apple platforms

`anyAppleOS`

The new availability shortcut replaces a long list of Apple platforms:

// Before
@available(macOS 27, iOS 27, watchOS 27, tvOS 27, visionOS 27, *)
func showStatus() { ... }

// After
@available(anyAppleOS 27, *)
func showStatus() { ... }

anyAppleOS also works in #if os(anyAppleOS).

`@C`

@C exposes a Swift function to C, and can also be used when Swift implements a C function. The signature must use C-compatible types such as integers, pointers, imported C structs, and raw-value enums:

@C
func averageLaunchWindowLength(_ windows: Span<LaunchWindow>) -> TimeInterval { ... }

Java and Android

Java can call Swift functions that are async or throwing, and Java classes can conform to Swift protocols. There is also an official Swift SDK for Android on swift.org.

WebAssembly

Swift compiles to Wasm with an open-source toolchain. JavaScriptKit's type-safe bridge is now 35–40 times faster than its dynamic path. Goodnotes was the example in the session: it moved Swift code from the native iOS app to the web through Wasm.

Embedded Swift

Embedded Swift now supports existential types, untyped throws, and DWARF debug information for inspecting coredumps on constrained hardware. The new EmbeddedRestrictions warning group reports features that will not work in an embedded environment.

Editor support

The Swift VS Code extension integrates Swiftly for toolchain management and is available through OpenVSX, which also makes it available in editors such as Cursor and VSCodium. It now includes a getting-started checklist as well.

Performance and ownership

Optimizer hints

@inline(always) is now a supported attribute. Class methods should use it together with final.

Swift 6.3's @specialized can pre-specialize a generic function for a known hot type:

@specialized(where Values == [UInt8])
func histogram<Values>(of values: Values) -> [256 of Int]
    where Values: Sequence<UInt8> { ... }

Ownership in the standard library

Equatable, Comparable, and Hashable now work with noncopyable types. Equatable and Comparable also work with non-escapable types, and associated types may be ~Copyable or ~Escapable.

The new Iterable protocol borrows elements in a for loop instead of copying them.

Custom borrow and mutate accessors make it possible to expose these semantics from a container:

public struct UniqueBox<Value: ~Copyable>: ~Copyable {
    private let valuePointer: UnsafeMutablePointer<Value>

    public var value: Value {
        borrow { valuePointer.pointee }
        mutate { &valuePointer.pointee }
    }
}

New low-overhead types

UniqueBox and UniqueArray provide noncopyable storage without reference-counting overhead.
Continuation checks single resumption at compile time, with the safety of CheckedContinuation and the cost of UnsafeContinuation.

Ref and MutableRef provide safe borrowed references into a collection slot:

var countRef = MutableRef(&counts[key, default: 0])
countRef.value += 1

withTemporaryAllocation now gives its closure an OutputSpan instead of an UnsafeMutableBufferPointer.

I will probably use @diagnose, the ignored-Task-error warning, and the Swift Testing additions first. The ownership types are more interesting, but I need an actual project with the right problem before they become useful.

Full session: What's new in Swift — WWDC26.

Configuration Is Easy; Maintenance Is the Work

Sat, 30 May 2026 00:00:00 GMT

Every clean environment I have built has stayed clean for about six months. The last time I looked closely, I found three Python versions where I expected one, a Brewfile that no longer described the machine, and a mise list full of runtimes installed for experiments I could no longer remember. Nothing was broken. The machine had simply drifted while I was using it.

This is the last article in the series. The previous six covered configuration—layers, settings, and dotfiles—but that is the part I can finish in an afternoon. Whether the setup is still clean a year later depends on a much smaller, recurring job: noticing drift and removing what no longer belongs.

What drift looks like

I usually find one of three things.

Silent auto-install. A tool provisions something without asking, as uv did with its own Python in the Python article. The machine gains state I did not choose, and there may be no warning at all, which makes this the easiest kind of drift to miss. Declarative settings prevent some of it: python-preference = only-system, for example, turns that silent download into a visible error. They do not catch every tool, so I still need a way to inspect the result.

Forgotten sync. I install something deliberately but forget to declare it. The Brewfile from the apps article then falls behind the actual machine. This rarely matters day to day; it matters during a migration, when every missing entry becomes “oh, I forgot I had that.” The fix is to reconcile the two states before I need the file for recovery.

Accumulated cruft. A runtime, global tool, or package was installed intentionally, used once, and never removed. This is the hardest kind to clean up: each item is valid on its own, so nothing reports an error. Only the accumulated list reveals the problem.

A health check should only make drift visible

I keep a few shell functions for this. Earlier articles introduced brewdiff, which compares the installed applications with the Brewfile, and zhealth, which finds stray zsh files in the home directory. Python needs a similar check because it is particularly easy for several tools to acquire different interpreters without making the disagreement obvious:

# 30-functions.zsh — surface Python version drift across tools
pyversions() {
  echo "shell PATH   : $(command -v python)"
  echo "  reports    : $(python --version 2>&1)"
  echo "mise current : $(mise current python 2>/dev/null || echo '—')"
  echo "uv would use : $(uv run python --version 2>&1)"
  echo "mise list    :"
  mise list python 2>/dev/null | sed 's/^/  /'
}

pyversions puts the shell's python, mise current, uv run python, and the installed mise versions in one view. If the first three agree, the Python layer is healthy. If they do not, some tool owns a Python I did not expect, and I can repeat the investigation from the Python article without first rediscovering all the commands.

The same pattern covers the other layers:

compare mise list with the mise.toml files I actually use;
compare the machine with the Brewfile through brew bundle check;
compare the contents of $HOME with the expectation that it contains one zsh file.

These checks do not repair anything. That is intentional. A small reporting command is easy to trust and easy to run; it turns drift from a surprise into a decision.

The 30-day test

For me, a mature setup is one with very few tools that are no longer used. That makes maintenance mostly a matter of subtraction.

For anything questionable, I ask whether I have actually used it in the last 30 days. A runtime, global tool, or application that has gone untouched for a month becomes a candidate for removal—not an automatic deletion, but something that now needs a reason to stay.

For mise runtimes, the pass is concrete:

$ mise list                 # what's installed
$ mise uninstall python@3.11 # remove a version no project uses
$ mise prune                 # drop versions nothing references

The Ruby decision in the previous article applies the same test before installation. An old system Ruby is not, by itself, a reason to add a mise-managed Ruby to a machine with no Ruby projects. Waiting until a project needs it avoids creating another runtime to audit and eventually remove.

I do this as a periodic cleanup instead of waiting until I feel motivated. Installing a new tool feels productive; removing one feels like losing something or admitting the original installation was a mistake. Sunk cost makes leaving it alone even easier. A schedule is less dramatic: run the checks, review what has not been used for 30 days, and remove what I cannot justify.

An empty line in mise list, a short Brewfile, or a home directory with one dotfile is not missing configuration. Sometimes it is the desired result.

Do not turn maintenance into another system

The cleanup itself can drift into over-engineering. It would be easy to build a dashboard, scheduled jobs, and a collection of checks elaborate enough to require their own maintenance.

That defeats the point. A brewdiff that takes two seconds gets used. A monitoring system that needs attention does not. Reconciliation only remains useful while its cost is lower than the mess it prevents, so I keep these tools small and let them report rather than automate every decision.

The manifesto started this series with four layers: System, Runtime version, Package manager, and Project dependencies. There is a fifth part that none of those layers can provide: occasionally looking at the machine, comparing it with the declared state, and bringing the two back together before something breaks.

On a machine I have not checked recently, I start with which python and uv run python --version, then look through mise list for anything untouched in a month. That is usually enough to show whether the environment I remember is still the one I have.

This is the final article in the Sovereign Tools series. The full set, in reading order, is on the series index.

One Architecture, Many Languages

Sat, 30 May 2026 00:00:00 GMT

When I start a project in an unfamiliar ecosystem, I want a short answer to four questions: who installs the runtime, who manages packages, which lockfile goes into git, and which generated files stay out. This article collects those answers for Node, Java, Swift, Rust, Go, and Ruby. It is a reference to revisit one section at a time.

The answers use the four layers introduced in the first article of this series:

<figure class="my-6"> <svg viewBox="0 0 600 330" role="img" aria-labelledby="diagram-layers-title-6" style="width:100%;height:auto;color:inherit"> <title id="diagram-layers-title-6">The four-layer stack: System, Runtime version, Package manager, Project dependencies</title> <g font-family="ui-sans-serif, system-ui, sans-serif"> <rect x="10" y="10" width="580" height="66" rx="10" fill="currentColor" fill-opacity="0.05" stroke="currentColor" stroke-opacity="0.15"/> <text x="30" y="38" font-size="13" font-weight="700" fill="var(--primary)">Layer 3</text> <text x="30" y="58" font-size="15" font-weight="600" fill="currentColor">Project dependencies</text> <text x="570" y="44" font-size="13" text-anchor="end" fill="currentColor" fill-opacity="0.6">lockfiles in git</text> <rect x="10" y="86" width="580" height="66" rx="10" fill="currentColor" fill-opacity="0.05" stroke="currentColor" stroke-opacity="0.15"/> <text x="30" y="114" font-size="13" font-weight="700" fill="var(--primary)">Layer 2</text> <text x="30" y="134" font-size="15" font-weight="600" fill="currentColor">Package manager</text> <text x="570" y="120" font-size="13" text-anchor="end" fill="currentColor" fill-opacity="0.6">uv, pnpm, cargo</text> <rect x="10" y="162" width="580" height="66" rx="10" fill="currentColor" fill-opacity="0.05" stroke="currentColor" stroke-opacity="0.15"/> <text x="30" y="190" font-size="13" font-weight="700" fill="var(--primary)">Layer 1</text> <text x="30" y="210" font-size="15" font-weight="600" fill="currentColor">Runtime version</text> <text x="570" y="196" font-size="13" text-anchor="end" fill="currentColor" fill-opacity="0.6">mise, or a sovereign tool</text> <rect x="10" y="238" width="580" height="66" rx="10" fill="currentColor" fill-opacity="0.08" stroke="currentColor" stroke-opacity="0.2"/> <text x="30" y="266" font-size="13" font-weight="700" fill="var(--primary)">Layer 0</text> <text x="30" y="286" font-size="15" font-weight="600" fill="currentColor">System</text> <text x="570" y="272" font-size="13" text-anchor="end" fill="currentColor" fill-opacity="0.6">Homebrew + Xcode CLT</text> </g> </svg> </figure>

For Layer 1 — Runtime version, I follow the rule from the sovereignty article: use the language's strong official tool when it has one; otherwise, let mise do the job. The sections below focus on the resulting setup and the places where it usually goes wrong.

Node.js / TypeScript

mise owns the Node version because Node has no sovereign version manager. I use pnpm for packages, but enable it through corepack rather than adding a separate brew install. This lets the packageManager field in package.json pin the pnpm version for the project.

# mise.toml
[tools]
node = "22"

[settings]
# let corepack manage the pnpm version from package.json's packageManager field

corepack enable      # ships with Node; activates pnpm/yarn shims

Avoid both brew install node and brew install pnpm. The first makes Homebrew the owner of Layer 1; the second bypasses the project's package-manager pin. Node does not need a separate virtual environment: node_modules is already local to the project, providing the isolation for which Python uses .venv.

For Node-based command-line tools, I normally use pnpm dlx when I only need to run something once. If a tool must be installed, I keep a deliberate PNPM_HOME on PATH instead of accumulating an uncontrolled set of npm install -g packages.

Commit pnpm-lock.yaml, and ignore:

node_modules/
*.tsbuildinfo
.turbo/
dist/

Java

Java has no single sovereign version tool, and the JDK itself comes in several distributions. I let mise install Temurin, a neutral and well-maintained default:

# mise.toml
[tools]
java = "temurin-21"

Check that mise is setting JAVA_HOME, not merely putting java on PATH. Many Java tools read JAVA_HOME directly, so an old value can silently override the JDK you meant to use. mise where java and echo $JAVA_HOME should point to the same installation:

mise where java
echo $JAVA_HOME

For the build tool, use the wrapper committed by the project—./gradlew or ./mvnw—rather than a global Gradle or Maven. The wrapper pins the build-tool version in the repository, applying the same Layer 3 discipline beyond ordinary dependencies.

Android is a separate case. Android Studio brings its own JDK and SDK, so I let it own that environment just as Xcode owns Swift.

Gradle and Maven declare dependencies in their build files. Commit those files and the wrapper, then ignore the build output:

.gradle/
build/
target/

Swift / iOS

Xcode is Swift's sovereign tool on macOS. It covers Layer 0 — System and Layer 1 — Runtime version together: toolchain, SDK, and build system all arrive as one application. I install it from the Mac App Store, which is why the apps article routes Xcode through mas, and prefer Swift Package Manager for dependencies.

Do not brew install swift on macOS. It creates a second claimant for the toolchain while Xcode still wins in less obvious parts of the build. CocoaPods also adds a Ruby dependency that most new projects no longer need; when SPM supports the packages involved, it keeps dependency management inside the Apple toolchain.

One of my projects has a boundary that has worked particularly well: KotobaLab is written in Swift, while its companion DictionaryBuilder is written in Python. They do not share a runtime, package manager, or build system. DictionaryBuilder writes a SQLite file and KotobaLab reads it. That neutral data interface lets both toolchains remain independent instead of making either ecosystem reach inside the other.

Commit Package.resolved, SPM's lockfile. Ignore the per-user and build artifacts:

xcuserdata/
DerivedData/
.build/
*.xcuserstate

Rust

Rust has the cleanest ownership model in this group. rustup owns Layer 1, while cargo, shipped with it, handles Layer 2 as well as building, testing, dependency management, and publishing.

# rustup installs the toolchain; cargo comes with it
rustup default stable

If a polyglot repository already has a mise.toml, it can instead contain rust = "1.78" and let mise proxy to rustup. This is the mise as proxy arrangement described in the sovereignty article. Both setups work; do not use both to manage the same project's Rust version.

Cargo already keeps dependencies per project, so Rust has no need for a virtual environment. For global command-line tools written in Rust, such as ripgrep, fd, and bat, I prefer the brew formula. It provides a prebuilt binary, whereas cargo install compiles the tool from source. I reserve cargo install for tools that have not been packaged yet.

Commit Cargo.lock for applications and binaries. The long-standing convention for libraries is to omit it so downstream users resolve their own versions. Ignore:

/target/

Go

Go's official dl installer is not a strong version manager, so I am comfortable letting mise own the Go version:

# mise.toml
[tools]
go = "1.23"

Modern Go uses modules, so projects no longer need the old GOPATH workspace layout and can live anywhere on disk. I do set GOBIN, however, so go install writes executables to a directory I control and already have on PATH. I use ~/.local/bin, the same location as personal scripts in the Python article:

# 00-env.zsh
export GOBIN="$HOME/.local/bin"

Commit both go.mod, which declares dependencies, and go.sum, which pins their checksums. Go leaves few incidental files in a repository; ignore compiled binaries by name or put them in an ignored output directory.

Ruby

Ruby has no sovereign version tool, so mise can own Layer 1. I only install it when a project actually requires Ruby.

Never use the system Ruby included with macOS for project dependencies. It is old, Apple discourages modifying it, and sudo gem install against it is a reliable way to damage the system environment.

# mise.toml — only when a project genuinely needs it
[tools]
ruby = "3.3"

CocoaPods is still a common reason for macOS developers to install Ruby, but SPM has removed that requirement from many Swift projects. If SPM covers the project, Ruby can stay uninstalled. This follows the on-demand approach from the maintenance article: the presence of an old system Ruby does not require adding a mise-managed Ruby to a machine with no Ruby projects.

When Ruby is necessary, commit Gemfile.lock. If Bundler uses a local path such as vendor/bundle/, ignore that directory.

What stays consistent across languages

A repository should declare its runtime rather than relying on a contributor's global default. Check in mise.toml or .tool-versions, and a fresh clone can provision the required versions with mise install. Global defaults are still useful for scratch work.

Lockfiles belong in git; derived artifacts do not. That means committing pnpm-lock.yaml, Cargo.lock, go.sum, Package.resolved, uv.lock, and Gemfile.lock, while keeping node_modules, target/, DerivedData/, .venv, and similar output in .gitignore.

One mise.toml can list node, python, and go together. A polyglot project does not need a separate runtime configuration for every language, and the whole toolset can be provisioned with one command. This unified interface remains useful even when mise delegates to a sovereign tool.

The same fact should not be declared twice, but superficially similar declarations may have different jobs. In Python, requires-python in pyproject.toml describes the range supported by the code. mise.toml selects the one version used on the current machine. Keeping both is not duplication; collapsing them would lose information. Actual duplication creates two sources of truth, which is the failure the first article set out to avoid.

There is also a hard limit to this model. C and C++ have no comparable owner for “the C version.” System compilers, SDKs, and multiple build systems blur the layers. I do not try to force these toolchains into the same shape. When C or C++ appears as a native extension or build dependency, I let the higher-level tool that introduced it handle the requirement.

The final article in the series covers what happens after this setup: keeping the environment usable without turning maintenance into another project.

When to Let the Official Tool Win

Sat, 30 May 2026 00:00:00 GMT

The previous article made mise the single owner of Python versions and kept uv at the dependency layer. On the same machine, though, I let rustup own Rust even though mise can install Rust too.

The difference is not a special exception for Rust. Before assigning Layer 1—the runtime version—I ask one question: does this language have a strong, official sovereign tool?

What counts as a sovereign tool

Here, a sovereign tool means an official version and toolchain manager that belongs to the language project itself. rustup for Rust and Xcode for Swift are the clearest examples. If one exists and is strong, I leave the layer to it. If the official option is absent or too limited, mise fills the gap.

“Official” alone is not enough. I look for four things:

It is part of the language project. It comes from the people shipping the compiler, rather than a third party trying to catch up with it.
It owns more than a version switch. That can include toolchain components, stable/beta/nightly channels, cross-compilation targets, and project pins recognized across the ecosystem. Merely selecting the active version is already something mise handles well.
The community has converged on it. “How do I install this language?” should have one routine, near-universal answer. Three competing answers mean there is no sovereign tool yet.
Its contract is stable across upgrades. Giving a tool this layer for years only works if routine upgrades do not break existing projects.

rustup clears all four: it is part of Rust, manages toolchains, targets, and release channels, is the standard installation path, and has kept a stable contract for years. Go's official dl installer is a useful counterexample. It fetches a particular Go version, but does little beyond that and has not become the accepted owner of version management. It is official, but it does not clear criteria 2 and 3, so I still treat it as weak.

<figure class="my-6"> <svg viewBox="0 0 600 300" role="img" aria-labelledby="diagram-sov-title" style="width:100%;height:auto;color:inherit"> <title id="diagram-sov-title">Decision tree: does the language have a strong sovereign tool?</title> <g font-family="ui-sans-serif, system-ui, sans-serif">  <rect x="140" y="20" width="320" height="58" rx="10" fill="currentColor" fill-opacity="0.05" stroke="currentColor" stroke-opacity="0.2"/> <text x="300" y="45" font-size="13.5" font-weight="600" text-anchor="middle" fill="currentColor">Strong, official sovereign tool?</text> <text x="300" y="65" font-size="11.5" text-anchor="middle" fill="currentColor" fill-opacity="0.55">part of the language · owns toolchain · consensus · stable</text>  <text x="150" y="108" font-size="12" font-weight="700" text-anchor="middle" fill="var(--primary)">Yes</text> <text x="450" y="108" font-size="12" font-weight="700" text-anchor="middle" fill="var(--primary)">No / weak</text>  <path d="M260 78 L150 120" stroke="currentColor" stroke-opacity="0.3" fill="none"/> <path d="M340 78 L450 120" stroke="currentColor" stroke-opacity="0.3" fill="none"/>  <rect x="30" y="125" width="240" height="150" rx="10" fill="currentColor" fill-opacity="0.05" stroke="currentColor" stroke-opacity="0.15"/> <text x="150" y="152" font-size="13" font-weight="600" text-anchor="middle" fill="currentColor">Defer to the sovereign tool</text> <text x="150" y="176" font-size="12" text-anchor="middle" fill="currentColor" fill-opacity="0.6">it owns Layer 1</text> <text x="150" y="210" font-size="12.5" text-anchor="middle" fill="currentColor" fill-opacity="0.7">rustup → Rust</text> <text x="150" y="232" font-size="12.5" text-anchor="middle" fill="currentColor" fill-opacity="0.7">Xcode → Swift</text>  <rect x="330" y="125" width="240" height="150" rx="10" fill="currentColor" fill-opacity="0.05" stroke="currentColor" stroke-opacity="0.15"/> <text x="450" y="152" font-size="13" font-weight="600" text-anchor="middle" fill="currentColor">mise fills the gap</text> <text x="450" y="176" font-size="12" text-anchor="middle" fill="currentColor" fill-opacity="0.6">mise owns Layer 1</text> <text x="450" y="208" font-size="12.5" text-anchor="middle" fill="currentColor" fill-opacity="0.7">Python · Node · Java</text> <text x="450" y="230" font-size="12.5" text-anchor="middle" fill="currentColor" fill-opacity="0.7">Ruby · Go (weak)</text> </g> </svg> </figure>

Applying it to the languages I use

These judgments are all about Layer 1: the runtime version.

Python: no sovereign tool. pyenv, mise, uv, the system Python, and other approaches coexist. I therefore let mise own Layer 1 and keep uv at Layer 2, as described in the Python article.
Rust: rustup is the sovereign tool. It installs Rust on my machine; mise does not.
Node.js: nvm, fnm, volta, and mise compete, with no official answer. I use mise.
Java: there is no sovereign tool, and Java also comes in multiple distributions. I use mise with Temurin as the default, a neutral choice that avoids reopening the distribution question for every project.
Swift / iOS: Xcode owns the toolchain, SDK, and build system and is shipped by Apple. On macOS, installing Swift through another manager means working against the platform, so I defer completely.
Go: the official option is too weak to own the layer. I am comfortable putting Go under mise, as many other users do.
Ruby: rbenv, rvm, chruby, and mise all exist; none is sovereign. When I need Ruby, mise owns its version.

`mise` can be a proxy

Deferring to rustup does not necessarily mean typing rustup for every operation. A project can still declare Rust in mise.toml:

# mise.toml
[tools]
rust = "1.78"

mise delegates to rustup; it does not reimplement Rust toolchain management. I think of this as mise as proxy: it provides the shared interface while rustup remains the owner and source of truth.

That leaves two sensible arrangements:

rustup-native: a Rust-only project talks to rustup directly. There is no polyglot setup to unify.
mise as the project interface: a polyglot project already pinning Python and Node in mise.toml can add rust = "1.78". Then mise install provisions the project through one declaration while delegating Rust to rustup.

The trap is mixing these arrangements inside one project until neither file is authoritative. The interface may be mise or rustup, but ownership of the Rust toolchain must remain with rustup.

The answers can change

I used the same test when looking at Zig. At the time, it did not have a strong official manager with community consensus, so mise or a simple manual installation was reasonable. Mojo falls into the same young-ecosystem category. Haskell is a useful edge case: GHCup is strong enough that deferring to it makes sense. Lua has no consensus tool, so mise fills the gap.

These are current judgments, not permanent assignments. If Python eventually ships a strong official manager and the community converges on it, I would move Python out of mise and defer to that tool just as I defer to rustup today.

The first article said that each kind of resource should have one owner. This test decides who that owner is for runtime versions. The next article turns the resulting choices into a concrete stack, including the pitfalls, lockfiles, and gitignore patterns for each language.

Making mise and uv Agree on Python

Sat, 30 May 2026 00:00:00 GMT

I noticed the problem because the same command returned different versions in two directories:

$ cd ~/project && uv run python --version
Python 3.12.7
$ cd ~ && uv run python --version
Python 3.13.1

The project result was expected: each project can pin its own runtime. The result in my home directory was not. I did not remember installing Python 3.13.1, and mise—which I use as the sole owner of runtime versions, as described in the first article in this series—did not know about it.

Finding the other Python

I first checked what python referred to in each context. The shell and uv run were using different binaries:

$ which python
/Users/me/.local/share/mise/installs/python/3.12.7/bin/python
$ uv run python -c 'import sys; print(sys.executable)'
/Users/me/.local/share/uv/python/cpython-3.13.1-macos-aarch64-none/bin/python3.13

The shell found the interpreter installed by mise and exposed on PATH. Outside a pinned project, however, uv run selected an interpreter under ~/.local/share/uv/python, a directory I had never intentionally populated.

uv's own list made the split explicit:

$ uv python list --only-installed
cpython-3.13.1-macos-aarch64-none    /Users/me/.local/share/uv/python/cpython-3.13.1-.../bin/python3.13
cpython-3.12.7-macos-aarch64-none    /Users/me/.local/share/mise/installs/python/3.12.7/bin/python3.12

There were two separate CPython builds. readlink -f confirmed that these were not two paths to the same binary: one belonged to mise, while the other had been downloaded and stored by uv.

This is normal uv behavior, not a bug. Its python-preference setting defaults to managed: prefer a uv-managed Python and, when no available interpreter satisfies a project's requires-python, download one. That is convenient when uv owns both the runtime and the packages. It conflicts with my setup because mise is supposed to be the only tool deciding which Python versions exist.

Interpreter, virtual environment, and cache

Before changing the setting, I needed to separate three things that all look like “Python files in hidden directories” but have different lifetimes and owners.

<figure class="my-6"> <svg viewBox="0 0 640 300" role="img" aria-labelledby="diagram-factory-title" style="width:100%;height:auto;color:inherit"> <title id="diagram-factory-title">Blueprint, sample unit, and shared library: mise install, .venv, and the uv cache</title> <g font-family="ui-sans-serif, system-ui, sans-serif">  <rect x="10" y="60" width="180" height="180" rx="10" fill="currentColor" fill-opacity="0.05" stroke="currentColor" stroke-opacity="0.15"/> <text x="100" y="40" font-size="13" font-weight="700" text-anchor="middle" fill="var(--primary)">Blueprint</text> <text x="100" y="92" font-size="13" font-weight="600" text-anchor="middle" fill="currentColor">mise install</text> <text x="100" y="116" font-size="12" text-anchor="middle" fill="currentColor" fill-opacity="0.6">python 3.14.0</text> <text x="100" y="150" font-size="11.5" text-anchor="middle" fill="currentColor" fill-opacity="0.5">one full interpreter</text> <text x="100" y="168" font-size="11.5" text-anchor="middle" fill="currentColor" fill-opacity="0.5">per version number</text> <text x="100" y="200" font-size="11.5" text-anchor="middle" fill="currentColor" fill-opacity="0.5">many versions</text> <text x="100" y="218" font-size="11.5" text-anchor="middle" fill="currentColor" fill-opacity="0.5">coexist</text>  <rect x="230" y="60" width="180" height="180" rx="10" fill="currentColor" fill-opacity="0.05" stroke="currentColor" stroke-opacity="0.15"/> <text x="320" y="40" font-size="13" font-weight="700" text-anchor="middle" fill="var(--primary)">Sample unit</text> <text x="320" y="92" font-size="13" font-weight="600" text-anchor="middle" fill="currentColor">project/.venv</text> <text x="320" y="124" font-size="11.5" text-anchor="middle" fill="currentColor" fill-opacity="0.6">bin/python → symlink</text> <text x="320" y="142" font-size="11.5" text-anchor="middle" fill="currentColor" fill-opacity="0.6">to the blueprint</text> <text x="320" y="186" font-size="11.5" text-anchor="middle" fill="currentColor" fill-opacity="0.6">site-packages =</text> <text x="320" y="204" font-size="11.5" text-anchor="middle" fill="currentColor" fill-opacity="0.6">the only private part</text>  <rect x="450" y="60" width="180" height="180" rx="10" fill="currentColor" fill-opacity="0.05" stroke="currentColor" stroke-opacity="0.15"/> <text x="540" y="40" font-size="13" font-weight="700" text-anchor="middle" fill="var(--primary)">Shared library</text> <text x="540" y="92" font-size="13" font-weight="600" text-anchor="middle" fill="currentColor">uv cache</text> <text x="540" y="124" font-size="11.5" text-anchor="middle" fill="currentColor" fill-opacity="0.6">content-addressable</text> <text x="540" y="160" font-size="11.5" text-anchor="middle" fill="currentColor" fill-opacity="0.6">one copy of a package</text> <text x="540" y="178" font-size="11.5" text-anchor="middle" fill="currentColor" fill-opacity="0.6">shared across all</text> <text x="540" y="196" font-size="11.5" text-anchor="middle" fill="currentColor" fill-opacity="0.6">projects</text>  <text x="210" y="135" font-size="18" text-anchor="middle" fill="currentColor" fill-opacity="0.4">←</text> <text x="210" y="152" font-size="10" text-anchor="middle" fill="currentColor" fill-opacity="0.5">symlink</text> <text x="430" y="135" font-size="18" text-anchor="middle" fill="currentColor" fill-opacity="0.4">→</text> <text x="430" y="152" font-size="10" text-anchor="middle" fill="currentColor" fill-opacity="0.5">link in</text> </g> </svg> </figure>

I think of a version installed by mise install python@3.14 as a blueprint: one complete interpreter identified by a version number. Several versions can coexist in mise's install directory, so 3.12.7 and 3.14.0 are simply two independent blueprints.

A project's .venv is a sample unit made from one of them. A virtual environment is mostly symlinks; its bin/python points back to the source interpreter instead of containing another copy. Its genuinely project-private part is site-packages. This makes a .venv small and quick to create, but it also means that removing a mise-managed Python breaks every environment whose bin/python points to it.

The uv cache is the shared library. It is content-addressable: a package version is stored once, then linked into each project's site-packages rather than repeatedly copied. If ten projects use the same version of numpy, they can refer to the same cached copy. Much of uv's speed comes from creating these links instead of downloading and unpacking the same files again.

In this model, mise supplies interpreters. uv creates project environments from them and fills those environments from its package cache. I did not need uv to provision another interpreter as well.

Restricting uv to system Python

uv reads global configuration from ~/.config/uv/uv.toml. I added one setting:

# ~/.config/uv/uv.toml
python-preference = "only-system"

The four possible values matter:

only-managed uses only uv-managed Pythons and ignores system interpreters. It provides the strongest isolation from the system and is the furthest from a mise-owned setup.
managed, the default, prefers uv-managed Pythons, falls back to system Pythons, and downloads a managed interpreter if neither satisfies requires-python. This was the source of my unexpected installation.
system prefers an interpreter already on PATH, but can still download a managed one when no suitable system interpreter exists.
only-system uses only system Pythons, including those that mise places on PATH, and never downloads one. If none satisfies the requirement, the command fails.

For my setup, that final failure mode is useful: a missing version remains visible until I install it through mise. Someone who wants to prefer mise without giving up uv's fallback can choose system instead.

After changing the setting, I removed uv's copy of Python 3.13.1 and rebuilt the affected environment:

$ uv python uninstall 3.13.1
$ cd ~/project && rm -rf .venv && uv sync

uv run python and the shell's python then agreed because both resolved to an interpreter owned by mise.

Existing projects can fail after the change

Changing a global selection rule also affects environments created under the old rule. I had older projects whose mise.toml requested Python versions that I had since removed from mise. Previously, uv sync could download the missing interpreter and continue. With only-system, it stopped:

error: No interpreter found for Python 3.11 in system path

That error means the project requests a Python that is not currently installed. The explicit repair is:

$ mise install python@3.11   # provision the blueprint, deliberately
$ uv sync                    # now succeeds, using mise's Python

When reopening an older project, I now:

Check requires-python in pyproject.toml and any version pinned in mise.toml.
Run mise install if that interpreter is missing.
Run rm -rf .venv && uv sync so the environment points to the installed interpreter.
Confirm the result with uv run python --version.

This adds a deliberate mise install step where the default configuration might have fixed the mismatch silently. I prefer seeing the missing runtime, but it is a real trade-off rather than free strictness.

I also keep uv.toml in my chezmoi source repository, alongside the files discussed in the dotfiles article, so the same rule follows me to another machine.

Small scripts do not need full projects

For a 40-line script that needs httpx, creating pyproject.toml, a .venv, and a lockfile is unnecessary. uv offers smaller paths that still obey only-system.

For a throwaway run, --with adds dependencies to a temporary environment:

$ uv run --with httpx --with rich script.py

For a script worth keeping, PEP 723 metadata records the Python requirement and dependencies in the file:

# /// script
# requires-python = ">=3.12"
# dependencies = ["httpx", "rich"]
# ///
import httpx
from rich import print
print(httpx.get("https://example.com").status_code)

Running uv run script.py makes uv read that metadata, assemble an environment from its cache, and execute the script without a project .venv. With a uv shebang, chmod +x, and a location such as ~/.local/bin, the script can also act like any other command on PATH while keeping its dependencies in the file. This has been much cleaner than the personal utilities I used to install into a global interpreter with pip install and later forget about.

Actual command-line tools belong in isolated tool environments. uv tool install handles persistent installations, while uvx runs a tool once; both fit utilities such as ruff or httpie better than a global pip install.

If mise is absent, letting uv own both Python and its packages is internally consistent, and the default managed behavior may be exactly right. My conflict existed only because two tools were making runtime decisions. The next article looks at how I decide when the official tool should own that layer instead.

The Brewfile Compromise: Eventual Consistency for Mac Apps

Sat, 30 May 2026 00:00:00 GMT

My Brewfile is often slightly out of sync with the applications installed on my Mac. I am fine with that.

This is looser than the setup in the Python article, where one owner controls the environment, or the dotfiles article, where stray configuration files are something to account for. Applications have a different failure mode, so I do not think they need the same enforcement.

Why I tolerate drift here

Layer 3 — Project dependencies needs strict consistency. When a lockfile specifies one version but a developer machine has another, the build may fail or behave differently from CI. The failure is immediate, and somebody else may have to pay for it. Exact versions and reproducible installs are worth the ceremony.

Layer 0 — System contains the applications and command-line tools installed by Homebrew. Suppose I run brew install today and forget to add the tool to my Brewfile. The current machine still works. I usually discover the omission much later, during a migration, when I restore from the Brewfile and the tool is missing. Then I install it and add the forgotten line.

That is a real cost, but it is deferred and usually small. For this layer, I accept day-to-day drift and reconcile it periodically: eventual consistency instead of the strict consistency I use for project dependencies.

Choosing an installation channel

On macOS I use three channels, in this order:

<figure class="my-6"> <svg viewBox="0 0 600 120" role="img" aria-labelledby="diagram-channels-title" style="width:100%;height:auto;color:inherit"> <title id="diagram-channels-title">Install channel priority: brew, then mas, then dmg</title> <g font-family="ui-sans-serif, system-ui, sans-serif"> <rect x="20" y="35" width="150" height="50" rx="10" fill="currentColor" fill-opacity="0.08" stroke="currentColor" stroke-opacity="0.2"/> <text x="95" y="58" font-size="13" font-weight="700" text-anchor="middle" fill="var(--primary)">brew</text> <text x="95" y="75" font-size="11" text-anchor="middle" fill="currentColor" fill-opacity="0.6">formula / cask</text> <text x="200" y="65" font-size="16" text-anchor="middle" fill="currentColor" fill-opacity="0.4">→</text> <rect x="225" y="35" width="150" height="50" rx="10" fill="currentColor" fill-opacity="0.05" stroke="currentColor" stroke-opacity="0.15"/> <text x="300" y="58" font-size="13" font-weight="700" text-anchor="middle" fill="currentColor">mas</text> <text x="300" y="75" font-size="11" text-anchor="middle" fill="currentColor" fill-opacity="0.6">App Store</text> <text x="405" y="65" font-size="16" text-anchor="middle" fill="currentColor" fill-opacity="0.4">→</text> <rect x="430" y="35" width="150" height="50" rx="10" fill="currentColor" fill-opacity="0.04" stroke="currentColor" stroke-opacity="0.12"/> <text x="505" y="58" font-size="13" font-weight="700" text-anchor="middle" fill="currentColor">dmg</text> <text x="505" y="75" font-size="11" text-anchor="middle" fill="currentColor" fill-opacity="0.6">last resort</text> </g> </svg> </figure>

I try Homebrew first. Formulae cover command-line tools and casks cover graphical applications. Homebrew already owns Layer 0 in this setup, and either kind of brew installation is easy to record in a Brewfile.

The Mac App Store comes second, through mas-cli. I use mas when an application depends on the Apple ecosystem—iCloud sync, Family Sharing, or App Store receipts—or is available only from the store. Otherwise I prefer a cask: it updates with the same brew command as everything else and does not require a signed-in App Store account.

A vendor-provided .dmg is the last resort. These installations cannot be expressed in the Brewfile, so I keep a manual-installs.md with the application name and its source. Without that file, the only record of what the Brewfile missed would be my memory.

One file for the intended state

mas-cli is useful because a mas entry lets App Store applications live in the same Brewfile as formulae and casks:

# Brewfile
tap "homebrew/bundle"

brew "ripgrep"
brew "mas"

cask "visual-studio-code"
cask "rectangle"

# App Store apps, by their numeric ID (mas list to find them)
mas "Things 3", id: 904280696
mas "Xcode", id: 497799835

With that file, brew bundle installs formulae, casks, and App Store applications in one pass. It is the single source of truth for what belongs on the machine, following the ownership model from the first article. The file may temporarily lag behind the machine, but there is still only one declared state.

How I reconcile it

Eventual consistency needs an actual convergence step. Mine starts with a read-only health check called brewdiff. It shows drift in both directions: installed but undeclared, and declared but missing.

# 30-functions.zsh — show drift between the Brewfile and the machine
brewdiff() {
  local brewfile="${HOMEBREW_BUNDLE_FILE:-$HOME/.config/homebrew/Brewfile}"
  echo "== Installed but NOT in Brewfile (undeclared) =="
  brew bundle cleanup --file="$brewfile" 2>/dev/null \
    | grep -E '^(Would uninstall|brew|cask|mas)' || echo "  (none)"
  echo
  echo "== In Brewfile but NOT installed (missing) =="
  brew bundle check --file="$brewfile" --verbose 2>/dev/null \
    | grep -v '^The Brewfile' || echo "  (all installed)"
}

This function only reports; it does not change the machine. I can inspect each undeclared item and decide whether it is a tool I meant to keep or an experiment I should remove.

For ordinary formulae, brewadd makes the common case cheaper by installing a package and appending it to the Brewfile in the same operation:

# install AND declare in one step
brewadd() {
  local brewfile="${HOMEBREW_BUNDLE_FILE:-$HOME/.config/homebrew/Brewfile}"
  brew install "$@" || return 1
  for pkg in "$@"; do
    grep -q "\"$pkg\"" "$brewfile" || echo "brew \"$pkg\"" >> "$brewfile"
  done
}

I also need a reminder, because a reconcile command that I forget to run is not much of a system. When a shell starts, this function checks the age of a timestamp file and nudges me if more than 30 days have passed:

# remind me to reconcile if it has been > 30 days
_brewdiff_reminder() {
  local stamp="$HOME/.cache/brewdiff-last"
  if [[ ! -f "$stamp" ]] || \
     [[ $(find "$stamp" -mtime +30 2>/dev/null) ]]; then
    print -P "%F{yellow}brewdiff:%f it's been a while — run 'brewdiff' to reconcile"
  fi
}
_brewdiff_reminder

Running brewdiff would touch the timestamp at the end and reset the clock. I have kept this deliberately small; any more friction would make the monthly check easy to postpone.

The Brewfile itself follows the chezmoi setup from the dotfiles article. A run_onchange_ script runs brew bundle on a new machine and whenever the Brewfile changes:

# run_onchange_brew-bundle.sh.tmpl
#!/bin/sh
# Brewfile hash: {{ include "dot_config/homebrew/Brewfile" | sha256sum }}
brew bundle --file="$HOME/.config/homebrew/Brewfile"

The hash in the comment is what triggers the script. Chezmoi sees the line change when the Brewfile checksum changes, so it reruns the command after an edit.

Letting an agent audit the list

For the monthly check, I sometimes give the brewdiff output to an AI agent. Its job is to explain each undeclared package and suggest keeping or dropping it, with a reason. It does not edit the Brewfile.

For example, an answer such as “pngquant is an image compressor and looks like a one-off; consider dropping it” saves me research time while leaving the decision visible. If the agent rewrote the file directly, a second actor would be changing the source of truth and the Brewfile would no longer represent only my intent. The useful delegation here is judgment, not authority.

The command I do not automate

brew bundle cleanup, including the --cleanup flag, uninstalls everything that is not in the Brewfile. That is convenient after the declaration is complete and dangerous while half of the tools I use are still undeclared. I do not run it with --force until brewdiff produces a short list whose contents I understand.

The monthly review is one case of the broader maintenance routine in the maintenance article: make drift visible, inspect it, and converge on a schedule. For Mac applications, that has been enough. I do not need every installation to update the Brewfile immediately; I need omissions to remain visible and cheap to repair.

Dotfiles Without .zshrc: ZDOTDIR and chezmoi

Sat, 30 May 2026 00:00:00 GMT

For a long time I could not tell which lines in my ~/.zshrc I had written and which ones came from an installer.

Installers append to your shell startup file as a matter of routine. You run an install script, it prints a cheerful "added initialization to ~/.zshrc", and that line is now load-bearing config you did not author and will not remember. Do this for two years and your ~/.zshrc becomes an archaeological dig: strata of half-remembered tools, some still installed, some long gone, none commented. The file works, so you never touch it, so it only grows.

I now keep only ~/.zshenv in the home directory. The rest lives under ~/.config/zsh/, split into small files and managed by chezmoi. This is the dotfiles version of the ownership model from the first article.

ZDOTDIR is zsh's own escape hatch

When zsh starts, it sources files in a fixed order. For an interactive login shell on macOS it is roughly:

/etc/zshenv      →  ~/.zshenv      (always, every shell)
/etc/zprofile    →  ~/.zprofile    (login shells)
/etc/zshrc       →  ~/.zshrc       (interactive shells)
/etc/zlogin      →  ~/.zlogin      (login shells)

The detail that changes everything is what ~/.zshenv is allowed to do. It runs first, for every invocation of zsh, and it is the one place you can set an environment variable that the rest of the startup sequence will respect. One of those variables is ZDOTDIR. If you set it, zsh reads .zprofile, .zshrc, and the rest not from $HOME but from $ZDOTDIR.

This is the official mechanism, not a hack. I call the result ZDOTDIR mode: set ZDOTDIR=~/.config/zsh in ~/.zshenv so zsh reads all of its configuration from ~/.config/zsh/, leaving the home directory with only ~/.zshenv.

So the entire contents of ~/.zshenv are one line:

# ~/.zshenv — the only zsh file allowed to live in $HOME
export ZDOTDIR="${XDG_CONFIG_HOME:-$HOME/.config}/zsh"

From here on, every other zsh file lives under ~/.config/zsh/. The home directory holds exactly one dotfile that zsh cares about, and its job is to point at where the real configuration lives.

<figure class="my-6"> <svg viewBox="0 0 600 300" role="img" aria-labelledby="diagram-home-title" style="width:100%;height:auto;color:inherit"> <title id="diagram-home-title">Home directory before and after ZDOTDIR mode</title> <g font-family="ui-monospace, SFMono-Regular, Menlo, monospace">  <text x="20" y="28" font-size="13" font-weight="700" font-family="ui-sans-serif, system-ui, sans-serif" fill="currentColor">Before</text> <rect x="20" y="40" width="250" height="240" rx="10" fill="currentColor" fill-opacity="0.05" stroke="currentColor" stroke-opacity="0.15"/> <text x="36" y="66" font-size="13" fill="currentColor" fill-opacity="0.85">~/</text> <g font-size="12.5" fill="currentColor" fill-opacity="0.6"> <text x="48" y="90">.zshenv</text> <text x="48" y="110">.zshrc</text> <text x="48" y="130">.zprofile</text> <text x="48" y="150">.bash_profile</text> <text x="48" y="170">.npmrc</text> <text x="48" y="190">.gitconfig</text> <text x="48" y="210">.python_history</text> <text x="48" y="230">.zsh_history</text> <text x="48" y="250">.cargo/ .rustup/ …</text> <text x="48" y="270" fill-opacity="0.4">(it keeps growing)</text> </g>  <text x="330" y="28" font-size="13" font-weight="700" font-family="ui-sans-serif, system-ui, sans-serif" fill="currentColor">After (ZDOTDIR mode)</text> <rect x="330" y="40" width="250" height="70" rx="10" fill="currentColor" fill-opacity="0.05" stroke="currentColor" stroke-opacity="0.15"/> <text x="346" y="66" font-size="13" fill="currentColor" fill-opacity="0.85">~/</text> <text x="358" y="90" font-size="12.5" fill="var(--primary)">.zshenv → sets ZDOTDIR</text> <rect x="330" y="125" width="250" height="155" rx="10" fill="currentColor" fill-opacity="0.05" stroke="currentColor" stroke-opacity="0.15"/> <text x="346" y="151" font-size="13" fill="currentColor" fill-opacity="0.85">~/.config/zsh/</text> <g font-size="12.5" fill="currentColor" fill-opacity="0.6"> <text x="358" y="173">.zshrc</text> <text x="358" y="193">00-env.zsh</text> <text x="358" y="213">20-aliases.zsh</text> <text x="358" y="233">30-functions.zsh</text> <text x="358" y="253">35-tools.zsh …</text> </g> </g> </svg> </figure>

A caveat worth stating early, because it is the usual objection: this is well-supported, but not universally. The VS Code integrated terminal honors ~/.zshenv and therefore picks up ZDOTDIR without any extra setup, which covers the editor most readers will care about. A small number of older tools assume your configuration is literally in ~/.zshrc and will not find it. When that happens you will know — the tool fails loudly rather than silently — and you can decide case by case whether to humor it. In two years it has come up rarely enough that I have not regretted the move.

A modular layout instead of one long file

Moving the file is half the work. The other half is not recreating the same monolith at the new address. Instead of one ~/.config/zsh/.zshrc, I keep a directory of numbered fragments, and the .zshrc does nothing but load them in order:

# ~/.config/zsh/.zshrc — loads every fragment in numeric order
for _file in "${ZDOTDIR}"/conf.d/*.zsh(N); do
  source "$_file"
done
unset _file

The (N) is a zsh glob qualifier that makes the pattern expand to nothing if the directory is empty, instead of erroring. The fragments live in conf.d/ with a numeric prefix that encodes load order:

~/.config/zsh/conf.d/
├── 00-env.zsh          # exported env vars, PATH base
├── 10-completion.zsh   # compinit and completion styles
├── 20-aliases.zsh      # short renames of existing commands
├── 30-functions.zsh    # shell functions that do real work
├── 35-tools.zsh        # eval-hooks for external CLIs (mise, zoxide, …)
├── 40-lang.zsh         # language/runtime-specific setup
├── 50-plugins.zsh      # zsh-ecosystem plugins
└── 90-local.zsh        # machine-specific, not tracked in git

The split is not cosmetic. Each prefix corresponds to a kind of thing, and the kinds have genuinely different lifecycles and ordering needs:

Aliases (20) only rename commands you already have. They are cheap and order-independent.
Functions (30) do actual work and may depend on env being set, so they come after 00-env.
Tools (35) are external CLIs that print a block of shell code for you to eval — mise activate, zoxide init, and so on. These are separated because they are not your code; they are generated hooks, and isolating them makes it obvious what is yours versus what a tool injected. This is the same instinct that started the article: keep authored config distinguishable from generated config.
Lang (40) is runtime-specific setup that needs the tool hooks from 35 already in place.
Plugins (50) are third-party zsh scripts, and they have the strictest ordering constraints.

Two ordering rules matter enough to call out. Plugins load after the language and tool setup, because a prompt plugin that shows your current runtime version needs mise to have been activated first — otherwise the prompt renders before the information it wants to display exists. And syntax-highlighting, if you use it, must be sourced last; it works by wrapping the line editor, and anything that touches the line editor afterward will fight it. The numeric prefixes make these rules visible in the directory listing rather than buried as a comment somewhere in a 400-line file.

Building PATH so it does not accumulate

There is one specific bug this layout invites, and it is worth fixing deliberately. ~/.zshenv runs on every shell, including nested ones. The naive way to add a directory to PATH is:

export PATH="$HOME/.local/bin:$PATH"

Run that in ~/.zshenv, open a shell, then open a shell inside that shell, and ~/.local/bin now appears in PATH twice. Tmux, subshells, and exec zsh all compound it. The list grows, lookups get slower, and reasoning about precedence gets harder.

The fix is to make the prepend idempotent — adding a directory that is already present should be a no-op:

# Prepend to PATH only if not already present.
path_prepend() {
  case ":$PATH:" in
    *":$1:"*) ;;            # already there — do nothing
    *) PATH="$1:$PATH" ;;
  esac
}

path_prepend "$HOME/.local/bin"

The case ":$PATH:" trick wraps PATH in colons on both ends so that even the first and last entries are bounded by colons, which means the *":$1:"* pattern matches them too. It reads as a small thing, and it is, but it is the difference between a PATH that is stable across re-sourcing and one that quietly bloats. Belonging in 00-env.zsh, it runs before anything that depends on PATH.

chezmoi: the source repo is not the target

So far everything is local files. To make them portable and version-controlled without symlinking a git repo straight into $HOME, I use chezmoi, which keeps a source directory under version control and renders it into your home directory. The piece worth understanding is that chezmoi encodes target-file metadata in the source filename through prefixes, so the source repo deliberately does not look like your home directory.

The prefixes I rely on:

dot_ — renders to a leading dot. dot_zshenv becomes ~/.zshenv. This exists because a source repo full of literal dotfiles would have everything hidden.
private_ — sets 0600 permissions on the result. Used for anything that should not be world-readable.
executable_ — sets the executable bit. Used for scripts in ~/.local/bin.
exact_ — on a directory, means "this is the complete contents; remove anything here that I did not declare." Powerful for enforcing that a directory holds only what you tracked.
run_onchange_ — not a file at all but a script chezmoi runs whenever its content changes. The mechanism behind "re-run the Brewfile when the Brewfile changed", which the apps article leans on.

So a slice of the source repo maps to target paths like this:

chezmoi source repo            →  rendered into $HOME
├── dot_zshenv                 →  ~/.zshenv
├── dot_config/
│   └── zsh/
│       ├── dot_zshrc          →  ~/.config/zsh/.zshrc
│       └── conf.d/
│           ├── 00-env.zsh     →  ~/.config/zsh/conf.d/00-env.zsh
│           └── 20-aliases.zsh →  ~/.config/zsh/conf.d/20-aliases.zsh
└── dot_local/
    └── bin/
        └── executable_zhealth →  ~/.local/bin/zhealth  (chmod +x)

The prefixes are declarative metadata: the filename states the intent (hidden, private, executable, exact) and chezmoi enforces it on every apply. This is the same single-source-of-truth idea from the manifesto, applied to dotfiles — the source repo is the one place the desired state of your home directory is written down, and chezmoi apply reconciles the machine to it.

The final form, and how to tell when it breaks

When this is in place, the home directory holds exactly one zsh file: ~/.zshenv. That fact is useful precisely because it is checkable. If a ~/.zshrc ever appears in $HOME, it did not come from me — some installer wrote it, and it is a pollution signal worth investigating, not ignoring.

Rather than remember to check, I make the check a command. This is a health-check function — a shell function that surfaces drift — and for the home directory I call it zhealth:

# 30-functions.zsh — flag stray zsh files in $HOME
zhealth() {
  local stray=(~/.zshrc(N) ~/.zprofile(N) ~/.zlogin(N) ~/.zshrc.*(N))
  if (( ${#stray} )); then
    print -u2 "zhealth: unexpected zsh files in \$HOME:"
    printf '  %s\n' "${stray[@]}" >&2
    return 1
  fi
  print "zhealth: \$HOME is clean — only ~/.zshenv expected"
}

Running zhealth after installing a new tool is how I catch an installer that decided to "helpfully" drop a ~/.zshrc back into my home directory. The point is not the function itself; it is that drift becomes visible on demand instead of accumulating silently. The maintenance article is entirely about this idea — turning cleanliness from a one-time setup into something a few small functions keep honest.

What not to track

A declarative dotfiles repo invites a tempting mistake: tracking everything. Some files should stay out of version control on purpose.

~/.zsh_history is state, not configuration. It is also private, and it changes on every command, so tracking it would mean an endless stream of meaningless diffs. Leave it local.
Caches and generated completion dumps (~/.config/zsh/.zcompdump*) are derived. They rebuild themselves; tracking them just creates churn.
Credentials, tokens, and anything secret do not belong in a plain dotfiles repo at all. chezmoi has template and secret-manager integration for the rare config file that must contain a secret, but the default answer is "do not put it here".

In practice this means a couple of ignore rules. .gitignore in the source repo keeps cruft out of git, and .chezmoiignore tells chezmoi not to manage specific target paths even if they exist:

# .chezmoiignore
.config/zsh/.zcompdump*
.zsh_history

The machine-specific fragment, 90-local.zsh, is the designated place for anything that should differ per machine or stay off the network — a work proxy, a local-only alias. It loads last so it can override, and it is the one fragment I deliberately do not track.

The result is one entry file in $HOME, a directory of ordered fragments, chezmoi as the declared state, and zhealth for the next installer that writes where it should not.

I Rebuilt My Mac Around Four Layers

Sat, 30 May 2026 00:00:00 GMT

A few weeks ago, I put a Mac mini into DFU mode (Device Firmware Update—the state where the machine has no operating system of its own and waits for another Mac to write one onto it) and erased everything.

There was a stubborn problem I wanted to fix, but I also wanted the machine to feel clean again. I expected a tedious afternoon of reinstalling software. Instead, the reset forced me to work out what “clean” was supposed to mean.

For a long time I treated it as a matter of installing fewer tools. That never lasted. Six months after setting up a supposedly minimal machine, I would have a ~/.zshrc I no longer understood, three Python interpreters I did not remember choosing, and a pip install from 2023 living somewhere it should not have been. The real problem was not the number of tools. I could no longer tell which one owned what.

This is the first of seven articles about the setup I rebuilt after that reset. The rest of the series goes into individual tools; this one records the four-layer model they fit into.

Reasonable installs add up

The mess usually starts with decisions that make sense on their own.

I need Python, so I run brew install python. A later project needs another version, so I add pyenv. Then a Node project brings in nvm, and Ruby brings in rbenv. Each installer adds a few lines to ~/.zshrc, often too quietly for me to notice. A pip install --user puts packages in a location that shadows what another tool expects.

None of those choices is obviously broken. The problem appears later, when I have to investigate my own computer to answer a basic question: when I type python, which Python runs, and why?

I wanted the answer to come from the structure of the setup, not from whatever happened to win the current PATH.

The four layers

I rebuilt the Mac mini around four layers, starting with the system and ending with the dependencies stored in each repository.

<figure class="my-6"> <svg viewBox="0 0 600 330" role="img" aria-labelledby="diagram-layers-title" style="width:100%;height:auto;color:inherit"> <title id="diagram-layers-title">The four-layer stack: System, Runtime version, Package manager, Project dependencies</title> <g font-family="ui-sans-serif, system-ui, sans-serif">  <rect x="10" y="10" width="580" height="66" rx="10" fill="currentColor" fill-opacity="0.05" stroke="currentColor" stroke-opacity="0.15"/> <text x="30" y="38" font-size="13" font-weight="700" fill="var(--primary)">Layer 3</text> <text x="30" y="58" font-size="15" font-weight="600" fill="currentColor">Project dependencies</text> <text x="570" y="44" font-size="13" text-anchor="end" fill="currentColor" fill-opacity="0.6">pyproject.toml + uv.lock, package.json + pnpm-lock.yaml</text>  <rect x="10" y="86" width="580" height="66" rx="10" fill="currentColor" fill-opacity="0.05" stroke="currentColor" stroke-opacity="0.15"/> <text x="30" y="114" font-size="13" font-weight="700" fill="var(--primary)">Layer 2</text> <text x="30" y="134" font-size="15" font-weight="600" fill="currentColor">Package manager</text> <text x="570" y="120" font-size="13" text-anchor="end" fill="currentColor" fill-opacity="0.6">uv, pnpm, cargo</text>  <rect x="10" y="162" width="580" height="66" rx="10" fill="currentColor" fill-opacity="0.05" stroke="currentColor" stroke-opacity="0.15"/> <text x="30" y="190" font-size="13" font-weight="700" fill="var(--primary)">Layer 1</text> <text x="30" y="210" font-size="15" font-weight="600" fill="currentColor">Runtime version</text> <text x="570" y="196" font-size="13" text-anchor="end" fill="currentColor" fill-opacity="0.6">mise (or a language's sovereign tool)</text>  <rect x="10" y="238" width="580" height="66" rx="10" fill="currentColor" fill-opacity="0.08" stroke="currentColor" stroke-opacity="0.2"/> <text x="30" y="266" font-size="13" font-weight="700" fill="var(--primary)">Layer 0</text> <text x="30" y="286" font-size="15" font-weight="600" fill="currentColor">System</text> <text x="570" y="272" font-size="13" text-anchor="end" fill="currentColor" fill-opacity="0.6">Homebrew + Xcode Command Line Tools</text> </g> </svg> </figure>

Layer 0 — System. Homebrew and the Xcode Command Line Tools install command-line tools and graphical applications. They do not install language runtimes. If Homebrew owns Python, the system layer has crossed into the next layer.

Layer 1 — Runtime version. This is the selected interpreter or compiler version: Python 3.14, Node 22, and so on. I usually let mise own this layer. It activates a runtime according to the project directory I am in.

Layer 2 — Package manager. uv installs Python packages, pnpm installs Node packages, and cargo installs Rust packages. These tools work inside a selected runtime; they do not decide which runtime version is active.

Layer 3 — Project dependencies. The manifest and lock files belong to the repository: pyproject.toml and uv.lock, or package.json and pnpm-lock.yaml. Another machine should be able to use these files to reproduce the same dependency set.

The direction of dependency matters. Project dependencies rely on a package manager; the package manager relies on a runtime; the runtime sits on the system. A tool can serve its own layer without quietly taking over the layer above or below it.

One owner for each kind of resource

The practical rule is simple: each kind of resource gets one owner.

Runtime versions have one owner. A project's libraries have one owner. System applications have one owner. If I ask where a Python came from, what pins a dependency, or why an application is installed, there should be one place to look.

This is also why counting tools did not help me. Two tools competing to manage Python create more confusion than five tools with separate jobs. What matters is whether their ownership overlaps.

The owner is not always mise. Rust has rustup, and Swift has Xcode. Both are strong, official toolchain managers maintained as part of their language ecosystems. When an official tool is good enough to own the runtime and toolchain, I let it do so instead of putting mise in front of it. The fifth article in this series explains the test I use for that choice.

“Single source of truth” therefore describes the ownership, not a favorite product. The tools can change without changing the model.

The recovery test

After the reset, recoverability became the useful test.

I should be able to delete caches and build artifacts—rm -rf the lot—and rebuild any project on the machine with one command. If that works, the caches really are disposable. If it does not, then something I called “derived” is carrying state that was never declared. I treat that as a layering problem and find the missing source of truth.

The declared state lives in manifests, lock files, and dotfiles. Together they should be enough to recreate the working state from close to nothing. This makes the setup predictable as well: I know which tool to inspect before I start debugging PATH.

There are limits to this setup. It is for one person on macOS who controls the whole machine. A team, a shared server, a locked-down corporate laptop, or another operating system can change the trade-offs substantially. mise and uv are also recent tools, and something else may replace them. Those constraints do not make the setup universal; they explain the environment in which I use it.

The next six articles

The remaining articles take one part of the setup at a time:

Dotfiles without .zshrc covers ZDOTDIR and chezmoi, making shell configuration declarative, exposing drift, and keeping the home directory from becoming a configuration dump.
The Brewfile compromise explains why eventual consistency is acceptable at the system layer and how a reconcile step keeps it honest without pretending it is strict.
Python, mise, and uv deals with uv quietly installing its own Python behind mise and the single setting that stops the conflict.
When to let the official tool win gives the test for choosing a language's own version manager instead of mise at Layer 1.
One architecture, many languages applies the same four layers to Node, Java, Swift, Rust, Go, and Ruby.
Configuration is easy; maintenance is the work covers health checks, subtraction, and the ongoing work required to keep the environment understandable.

The series index has the complete reading order and current status.

How I Learned to Read Swift Function Signatures

Thu, 07 May 2026 00:00:00 GMT

When I started learning Swift, I would open Apple’s DocC documentation, see something like this, and skip straight to the examples:

func compactMap<ElementOfResult>(
    _ transform: (Self.Element) throws -> ElementOfResult?
) rethrows -> [ElementOfResult]

My honest reaction was: “Why the hell does one function need to look this terrifying?”

Python had taught me to expect APIs that looked more like this:

map(func, arr)
filter(func, arr)

The Swift version seemed to pack generics, Optional, associated types, protocol constraints, throws, and rethrows into the same line. I treated all of that as syntax to get past, not information worth reading.

That worked for copying an example. It did not help much when I had to understand an unfamiliar API on my own.

Reading the arrows first

The signature that made this easier was map:

func map<T>(
    _ transform: (Element) throws -> T
) rethrows -> [T]

I no longer try to understand every symbol at once. I start with the value flowing through the function:

the method works on a collection of Element;
its closure accepts one Element;
the closure produces some type T;
map collects those values into [T];
the closure is allowed to throw;
because the method is rethrows, map throws only when the closure passed to it throws.

Read that way, the type signature is already a compact description of the operation. The generic name does not tell me what T is, but it tells me that the input element and output value do not have to be the same type.

`map`, `compactMap`, and `flatMap`

These three methods were where signatures first became more useful to me than memorized examples.

At first, I only knew the call pattern:

arr.map { ... }

Then I compared the return types and the closure return types. compactMap has an extra ? in one crucial place:

func compactMap<ElementOfResult>(
    _ transform: (Element) throws -> ElementOfResult?
) rethrows -> [ElementOfResult]

The transform may return either an ElementOfResult or nil, but the final array contains non-optional ElementOfResult values. In practical terms, it transforms every input and discards the nil results. That is the part I had previously remembered only as “use this when optionals are involved.”

The sequence overload of flatMap looks heavier:

func flatMap<SegmentOfResult>(
    _ transform: (Element) throws -> SegmentOfResult
) rethrows -> [SegmentOfResult.Element]
where SegmentOfResult : Sequence

The where clause says that each transformed result must itself be a Sequence. The return type then gives away the rest: the method returns an array of that inner sequence’s elements, not an array of sequences.

So a nested value such as:

[[1], [2,2], [3,3,3]]

can become:

[1,2,2,3,3,3]

Once I saw that relationship in the types, flatMap stopped feeling like an “advanced map.” For this overload, it means transforming elements into sequences and flattening those sequences into one array.

Small signatures also carry policy

Not every useful signature is full of generics. This one tells me almost everything I need to know:

func popLast() -> Element?

The result is optional, so an empty collection is represented by nil. I do not need to guess whether absence is a valid result.

That also makes the difference between these two names worth noticing:

removeLast()

and:

popLast()

removeLast() requires the collection to be nonempty and traps otherwise. popLast() handles the empty case by returning nil. The names hint at the difference, while the optional return type makes it explicit.

A small vocabulary covers a lot

After a while, I found that many intimidating signatures were combinations of a few forms:

(Element) -> T
(Element) -> T?
Sequence<Element>
where T : BinaryInteger

I read them as:

a function from Element to T;
a function that may or may not produce a T;
a sequence whose element type is Element;
a generic T constrained to conform to BinaryInteger.

This is more useful than memorizing one call site because the same relationships appear across the standard library and third-party APIs.

Where the complexity goes

Swift often asks me to accept:

more complexity during compilation

rather than leave:

more uncertainty at runtime

The trade is not absolute, but the compiler and the type system can catch or represent some of that uncertainty earlier.

Optional, generics, protocol-oriented APIs, type constraints, and explicit error handling all contribute to the longer signatures that initially put me off. They do not make every invalid state impossible, and a signature cannot replace all documentation. But it can expose input, output, failure, and type relationships before I run the code.

I still open examples when a type is unfamiliar. The difference is that I now read the signature first, then use the example to confirm the model I got from it.

The Raptor Dilemma

Sat, 02 May 2026 00:00:00 GMT

After comparing Astro, Saga, Toucan, Publish, Ignite, and Raptor, I wrote in Swift for Static Sites that Swift seemed most useful for content modeling and generation, while HTML, CSS, and JavaScript should remain the UI layer.

That was based partly on reading documentation and examples. Then I built an actual Raptor theme.

Raptor was pleasant while the pages were simple. As soon as I tried to reproduce the details of a custom blog theme, however, I was thinking in Swift and debugging in CSS. That gap—not a particular bug—was the real problem.

Why Raptor felt good at first

Raptor is more than a static site generator. It provides a Swift-first model for pages, layouts, themes, styles, and components. Instead of writing this:

<article class="post-card">
  <h2>Title</h2>
</article>

I could write:

VStack {
    Text(post.title)
}
.style(PostCardStyle())

The appeal is easy to understand: type safety, composability, one implementation language, and a developer experience that resembles SwiftUI. In theory, the same ideas that made SwiftUI productive on Apple platforms can make a website pleasant to build.

For simple pages, they do. These components are concise:

Text("Hello")
Button("Read more")

Landing pages, documentation sites, and basic blogs fit the model well. If most of the interface can be described as:

Text + Button + Grid + Card

Raptor is expressive and fast.

A custom theme exposes the boundary

The trouble started with ordinary theme details rather than an exotic browser feature.

A metadata row

In CSS, a row with categories on one side and a timestamp on the other can be expressed directly:

.meta {
  display: flex;
  justify-content: space-between;
}
.meta time {
  float: right;
}

The Raptor version rewrites the same intent as a component layout:

HStack {
    categories
    Spacer().axis(.horizontal)
    time
}
.style(Property.width(.percent(100)))

This version is fine, and arguably cleaner. The abstraction still matches the problem.

A pseudo-element used for decoration

The next detail was a small accent bar:

.recent-info::after {
  content: '';
  width: 13%;
  height: 5px;
  background: var(--accent);
  position: relative;
  bottom: -6px;
}

In Raptor, I represented it as a component:

RecentInfoAccentBar()

That works, but the meaning has changed. CSS treats the bar as a decorative layer attached to an element. The component tree treats it as structure. I was no longer only styling the existing document; I was changing the document structure to reproduce a styling technique.

A hover relationship

CSS selectors can also describe a relationship between two elements:

.card:hover .read-more {
  background-color: var(--bg-hover);
}

There was no equally clean expression for this in the Raptor component model. I either had to redesign the interaction or coordinate the relevant styles manually. The browser already understands the parent-hover/descendant relationship; the Swift abstraction did not make that relationship easier to state.

A negative margin

Even a familiar layout adjustment remains a CSS operation:

.read-more {
  margin-top: -21px;
}

Raptor can express it:

.style(Property.marginTop(.px(-21)))

But by this point I had not escaped CSS. I had translated CSS into Swift syntax.

The mismatch can be summarized like this:

They think in Swift,
but debug in CSS.

They write components,
but fight layout at the DOM level.

They define styles,
but still rely on raw CSS properties.

The theme ended up with two mental models

A typical card began as a useful Swift component:

PostListItem {
    PostMeta(...)
    PostTitle(...)
    PostExcerpt(...)
    PostReadMore(...)
}

Reusable styles kept the first layer tidy:

.style(PostCardStyle())

Then the visual adjustments accumulated:

.style(Property.marginTop(.px(12)))
.style(Property.paddingLeft(.px(8)))
.style(Property.fontSize(.px(14)))

The generated page still runs on HTML, CSS, and JavaScript, so browser behavior remains the source of truth. The working model became:

Structure → Swift
Styling → CSS concepts
Layout debugging → Browser DevTools

The daily experience was therefore:

Half SwiftUI
Half traditional Web

Raptor had moved the complexity, not removed it. I wrote components in Swift, inspected the resulting DOM, and fixed layout using knowledge of CSS.

Saga keeps the Web boundary visible

Saga takes a different approach. A template can still use Swift for composition while leaving the generated HTML and its classes obvious:

article(class: "mx-auto max-w-3xl px-6 py-12") {
  h1(class: "text-4xl font-bold tracking-tight") {
    item.title
  }
  div(class: "prose") {
    raw(item.body)
  }
}

The division of responsibility is explicit:

Swift → structure + composition
HTML → structure
CSS → styling

There is less translation between the code I author and the page I debug. For a visually demanding site, I find this easier to reason about than a SwiftUI-style layer over the browser.

Where I would use Raptor

Swift can express a Web UI; the question is how much distance from the rendering platform is useful.

For a generic interface:

Abstraction helps

For a highly customized interface:

Abstraction fights the platform

Raptor is strongest in the first case: structured pages made from familiar components, where its type safety and composition do real work. It becomes less comfortable in the second, precisely when selectors, pseudo-elements, and small layout adjustments matter most.

The broader stack still has two layers:

Rendering layer → HTML / CSS / JS
Authoring layer → Swift / React / Astro

React and Astro stay relatively close to the rendering layer. Raptor deliberately moves farther away, which gives it a distinctive SwiftUI-like experience but also creates the mismatch I hit while building the theme.

My practical boundary after this project is:

Swift for logic → great
Swift for UI abstraction → situational
HTML/CSS/JS → still the source of truth

I would still choose Raptor for a simple, structured Swift site. For a visual-heavy theme, I would rather use a Saga-style approach and keep the browser’s own UI model visible.

Swift for Static Sites

Fri, 01 May 2026 00:00:00 GMT

I recently tried to answer a practical question: if I move a visually complex blog theme to a Swift static site generator, which one should I use?

I went through Saga, Toucan, Publish, Ignite, and Raptor, then compared them with Web-native tools such as Astro, Hexo, Hugo, and Jekyll.

After reading their source and examples and trying them myself, I found that the choice depends less on feature count than on where Swift sits in the stack. A SwiftUI-like component API and a Swift program that generates ordinary HTML may look similar in a small demo, but they behave very differently once the design needs custom CSS.

The browser is the UI runtime

SwiftUI works on iOS because its abstractions connect to a system UI runtime:

iOS:
System UI runtime
→ SwiftUI Button / VStack / NavigationStack
→ Your Swift code
Web:
Browser runtime (DOM + CSS + JS)
→ HTML <button> / <div> / <article>
→ CSS grid / flex / selectors
→ Your HTML/CSS/JS

A SwiftUI Button is connected to platform behavior including accessibility, focus, animation, and input. A button declared through Raptor or Ignite eventually becomes:

<button class="...">Save</button>

plus CSS. The browser does not know about the Swift component that produced it; it only receives HTML, CSS, and JavaScript.

This is not an argument against declarative UI. React, Vue, and Astro are declarative too. The important difference is the object being declared and how closely it matches the browser's own model.

Framework	What you declare	Distance from the platform
SwiftUI	Native UI tree	Very close
React / Vue	DOM / component tree	Very close
Astro	HTML + islands	Very close
Saga / Publish	HTML output tree	Close
Ignite	Swift components (Bootstrap-like)	Medium
Raptor	SwiftUI-like UI + style system	Farther

SwiftUI maps closely to its platform. React still models the DOM, and Astro treats HTML as a first-class part of the component. Ignite and Raptor move the working model farther upward into a Swift component tree. That can be pleasant for a simple page, but the extra translation becomes visible in a heavily customized theme.

Where the component DSL stops helping

Ignite-style components are convenient for straightforward UI:

Text("Hello")
Button("Read More")
Grid {
  Card { ... }
}

With Bootstrap underneath, layout, spacing, responsiveness, and basic visual hierarchy arrive quickly. That is a good fit for documentation, portfolios, basic blogs, and other sites that can stay near the framework's built-in vocabulary.

A migrated visual theme is usually less cooperative. It may depend on CSS such as:

.card::before
.sidebar:has(.active)
grid-template-columns: minmax(0, 1fr) 18rem
position: sticky
backdrop-filter
mask-image
container queries

Once the built-in components no longer express the design, the Swift code falls back to lower-level HTML wrappers:

Tag("aside") { ... }
.class("layout-shell__sidebar")

The CSS still has to be written. The page is now split between a SwiftUI-style vocabulary and direct HTML and CSS, so the abstraction no longer removes much work.

The useful range for this approach is still real:

Simple sites
Docs
Portfolios
Basic blogs
Bootstrap-like layouts

The difficulty begins when a theme originally built in Astro or Hexo relies on precise selectors, pseudo-elements, layout rules, and browser-specific behavior. This is a boundary of the abstraction, not a defect in declarative UI or in the frameworks themselves.

Saga keeps the boundary visible

Saga takes a different route. It uses Swift for the parts where Swift is useful and leaves browser concerns in Web-native forms:

Swift:
Content model
Pipeline
Generation logic
Type safety

Web:
HTML structure
CSS styling
JavaScript behavior

A template can look like this:

article(class: "mx-auto max-w-3xl px-6 py-12") {
  h1(class: "text-4xl font-bold tracking-tight") {
    item.title
  }
  div(class: "prose prose-slate dark:prose-invert") {
    raw(item.body)
  }
}

This is Swift generating HTML, not an attempt to reproduce SwiftUI in a browser. The division remains easy to inspect:

Swift-native:
Types, functions, composition

Web-native:
HTML, CSS, browser semantics

For this kind of project, that directness matters more than having a larger UI abstraction.

Tailwind makes Saga more practical

Without Tailwind, a Saga template resembles conventional HTML with named CSS classes:

article(class: "post-card") {
  h2(class: "post-card__title") {
    item.title
  }
}

With Tailwind, the layout and styling remain next to the generated HTML:

article(class: "group rounded-3xl border border-slate-200 bg-white p-6 shadow-sm transition hover:-translate-y-1 hover:shadow-lg") {
  h2(class: "text-2xl font-semibold tracking-tight") {
    a(href: post.url) {
      post.title
    }
  }
}

There is no need to translate each CSS concept into a Swift modifier API. Tailwind is still CSS, expressed through utility classes, so the browser-facing model stays recognizable.

Raptor and Ignite fit different jobs

Raptor is more ambitious than a conventional static site generator. It defines a broad site model:

Site
Page
PostPage
CategoryPage
Layout
Theme
Style
PostWidget

It also integrates with Vapor for server-side rendering. That makes it interesting for Swift-first content platforms, static and dynamic hybrid sites, and projects that need backend integration.

The site model does not automatically make a complex front end easier to express, however. When the theme exceeds its UI and style system, the implementation returns to:

Tag + Div + Class + CSS

At that point I would want the higher-level model to solve a separate problem—content architecture or server integration, for example—because it is no longer reducing the front-end work.

Ignite makes a more pragmatic trade:

Swift API + Bootstrap

It is fast for a small site, portfolio, or documentation project. The trade-off is that Bootstrap's structure and visual assumptions become harder to hide when the site needs a distinctive theme.

Why I would still use Astro for the complex theme

If Swift is not itself a project requirement, Astro remains the safer choice for this particular job:

HTML, CSS, and JavaScript are first-class;
its components stay close to browser primitives;
Tailwind integration is straightforward;
Content Collections provide structure;
the ecosystem is mature.

That does not make Swift incapable of building websites. It means the cost of the Swift abstraction has to buy something the project needs.

The two Swift approaches I compared can be summarized as:

SwiftUI-style Web DSL (Raptor / Ignite)

Swift expresses UI
→ translated into HTML/CSS

Swift-native generation + Web-native UI (Saga)

Swift handles logic and structure
HTML/CSS/JS express the UI

For a highly customized visual site, I prefer the second model. Swift still provides types, functions, composition, content modeling, and generation logic, while HTML, CSS, and JavaScript retain control of the UI.

My practical shortlist after the comparison is:

Not using Swift: Astro + Tailwind
Using Swift seriously: Saga + Tailwind
Quick Swift site: Ignite
Exploring Swift Web frameworks: Raptor

Building a Personal Website in Swift

Tue, 21 Apr 2026 00:00:00 GMT

While building this site with Raptor, I needed distinct styles for post dates, navigation labels, tags, and other small pieces of text. I expected this to be a minor theme change. Instead, I ended up modifying the framework before realizing that I was working in the wrong layer.

Raptor is a static site generator written in Swift. Its layouts use Swift rather than HTML templates or JSX:

VStack {
    Text("Hello, world!")
    Text("Welcome to my site")
}

It also provides a theme system for typography and colors:

.font(.title1)
.fontSize(36, for: .title1)

That felt expressive and type-safe, and using Swift for a site was genuinely fun. The trouble started when the design needed more than the built-in text roles.

The roles missing from a real site

Raptor's typography system has a fixed set of roles:

body
title1 … title6
codeBlock

A real site also has post metadata, navigation labels, tags, categories, buttons, and links. In Hugo, Hexo, or a hand-written template, I would give those elements class names and move on:

<span class="post-meta">April 20</span>
<a class="nav-label">Archive</a>

.post-meta {
  font-size: 12px;
  color: gray;
}
.nav-label {
  font-weight: bold;
}

Raptor had no equivalent built-in roles for:

.postMeta
.navLabel

My first reaction was to add them.

Extending Theme

I designed an API that looked like this:

Text("April 20").textRole(.postMeta)

The theme would configure each custom role:

.fontSize(12, for: .postMeta)
.fontWeight(.medium, for: .postMeta)

Raptor would then generate:

.text-role-post-meta {
  font-size: 12px;
  font-weight: 500;
}

and attach the class to the rendered HTML:

<p class="text-role-post-meta">April 20</p>

After digging through the framework, I modified the theme configuration, updated CSS generation, and patched the rendering logic. The implementation worked: custom roles went through the theme system, supported light and dark mode, generated CSS automatically, and appeared in the final HTML.

The code was functional, but the model still felt wrong.

First, it created two competing ways to describe text:

.font(.title1)        // built-in
.textRole(.postMeta)  // custom

Second, the two APIs did not carry the same meaning. In Raptor:

.font(.title1)

selects an HTML tag such as <h1> and applies its styling. My custom API:

.textRole(.navLabel)

only applied styling. HTML structure and visual style are separate concerns, but I had added another typography API without resolving that distinction.

Eventually I was writing:

.tag(.h1)
.textRole(.navLabel)

which was just a more elaborate way to express:

<h1 class="nav-label"></h1>

The type-safe API was no longer removing complexity. It was recreating HTML concepts with extra steps.

The abstraction was already there

I checked other static site generators to see whether they modeled this problem at the framework level. Hugo, for example, simply allows:

<p class="post-meta"></p>

and leaves the rest to CSS.

That comparison sent me back into Raptor's design and source code. Theme is meant for global design tokens such as typography, colors, and spacing. A semantic style like “post metadata” does not need to become another global text role.

Raptor already has a separate abstraction for that: Style.

struct PostMetaStyle: Style {
    func style(content: Content, environment: EnvironmentConditions) -> Content {
        content
            .font(.caption)
            .foregroundStyle(.secondary)
    }
}

It can be applied directly to the content:

Text("April 20")
    .style(PostMetaStyle())

This serves the same purpose as:

<p class="post-meta">April 20</p>

but keeps the implementation reusable, composable, and type-safe.

Style also receives environment conditions, including the light or dark color scheme, active theme, contrast settings, and layout conditions. A semantic style can therefore adapt without becoming part of the theme's role system:

struct PostMetaStyle: Style {
    func style(content: Content, environment: EnvironmentConditions) -> Content {
        if environment.colorScheme == .dark {
            content.foregroundStyle(.gray)
        } else {
            content.foregroundStyle(.secondary)
        }
    }
}

The boundary I had missed was simple: Theme defines global tokens; Style packages reusable semantic styling. The framework already supported what I wanted—I had just started by changing its internals instead of using the abstraction intended for the job.

Recreating Apple Music’s Disappearing Navigation Title in SwiftUI

Fri, 03 Apr 2026 00:00:00 GMT

In Apple Music on iOS 26, scrolling can make the large navigation title and its toolbar content disappear. It does not follow the large-title behavior that iOS has used since iOS 11.

The usual transition is:

Large Title
   ↓ scroll
Small Navigation Title

Apple Music instead looks more like this:

Large Title
   ↓ scroll
(no title)

There is no public SwiftUI modifier dedicated to this interaction. Depending on how closely the result needs to match, I would use one of two implementations: build a custom header and control it from the scroll position, or hide only the compact title with an empty principal toolbar item.

The controllable version: own the header

A full implementation can combine:

a custom top header inserted with safeAreaInset(edge: .top)
scroll detection through ScrollGeometry
separate visibility rules for the title and other toolbar items
opacity and offset animations

SwiftUI already exposes the pieces:

.onScrollGeometryChange(...)
.safeAreaInset(...)
.toolbar(...)

They are building blocks rather than one navigation-bar option. A minimal version can track the vertical content offset and hide the header after a threshold:

struct CollapsingHeaderView: View {

    @State private var headerHidden = false

    var body: some View {
        ScrollView {
            VStack {
                ForEach(0..<50) { i in
                    Text("Row \(i)")
                        .frame(maxWidth: .infinity)
                        .padding()
                }
            }
        }
        .onScrollGeometryChange(for: CGFloat.self) { geometry in
            geometry.contentOffset.y
        } action: { _, offset in
            headerHidden = offset > 40
        }
        .safeAreaInset(edge: .top) {
            header
                .opacity(headerHidden ? 0 : 1)
                .animation(.easeInOut, value: headerHidden)
        }
    }

    private var header: some View {
        HStack {
            Text("Library")
                .font(.largeTitle.bold())

            Spacer()

            Image(systemName: "person.crop.circle")
        }
        .padding()
        .background(.ultraThinMaterial)
    }
}

This works with content built from ScrollView, List, or LazyVStack, and the header can contain any layout or transition the screen needs. The hiding threshold is also under the app’s control.

The tradeoff is that the app now owns the behavior, including scroll direction, toolbar layout, refresh interactions, and nested navigation-stack edge cases. That is reasonable for a screen that needs a precise result, but excessive if the only goal is to remove the compact title.

The small shortcut: empty the compact title

For the lighter version, place an empty view in the principal toolbar position:

.toolbar {
    ToolbarItem(placement: .principal) {
        Text("")
    }
}

Keep the normal large title:

.navigationTitle("Library")
.navigationBarTitleDisplayMode(.large)

The resulting transition is:

Large Title
   ↓ scroll
(empty)

The large title still appears at the top of the list. Once it collapses, the principal item supplies an empty compact title:

NavigationStack {
    List(items) { item in
        Text(item.title)
    }
    .navigationTitle("Library")
    .navigationBarTitleDisplayMode(.large)
    .toolbar {
        ToolbarItem(placement: .principal) {
            Text("")
        }
    }
}

This is enough to make a standard NavigationStack resemble Apple Music without introducing scroll state.

What the shortcut actually changes

SwiftUI normally transitions between these title states:

Large Navigation Title
        ↓
Compact Navigation Title

The principal toolbar item replaces the content shown in the compact position. Making that item empty changes the visible result from:

Large Title
   ↓
Small Title

to:

Large Title
   ↓
(blank space)

The navigation bar has not been removed. Its compact title simply renders no content, which is why the effect looks convincing while requiring almost no code.

That distinction also defines the limits of the trick:

the navigation bar still exists
other toolbar items may continue to occupy space
the result depends on current SwiftUI rendering behavior and may change in a future release

If the whole header and its layout must disappear, the custom scroll-driven version is the appropriate one. If an empty compact title is visually sufficient, the toolbar shortcut is much cheaper.

An official API may eventually replace both

Apple has introduced UI behavior in system apps before exposing related public APIs. .searchable, large navigation titles, and the tab-bar minimization behavior shown in Apple Music followed that general pattern.

A future SwiftUI API could conceivably look like:

.navigationBarCollapseBehavior(.onScroll)

or:

.toolbarScrollVisibility(.hidden)

Those modifiers are only illustrative; SwiftUI does not currently provide them.

Use Docker to Deploy a Minecraft server

Thu, 15 Jan 2026 00:00:00 GMT

Recently, I wanted to start a Minecraft server on my Mac. It’s quite simple to run ./run.bash in the server directory, but obviously not elegant enough since you have to keep the terminal and Java process running in the background. Screen can hide the terminal, but it has no idea about the Java service itself.

Docker is a powerful tool for deploying complicated services on almost any device. So I wondered if I could use Docker for the Minecraft server too.

And luckily, we have itzg/minecraft-server!

Intro

The GitHub link:

::github{repo="itzg/docker-minecraft-server"}

Here is a simple introduction from its documentation:

This docker image provides a Minecraft Server that will automatically download the latest stable version at startup. You can also run/upgrade to any specific version or the latest snapshot. See the Versions section below for more information.

To simply use the latest stable version, run

docker run -d -it -p 25565:25565 -e EULA=TRUE itzg/minecraft-server

where, in this case, the standard server port 25565 will be exposed on your host machine.

Docker Compose

I do not recommend running the image directly with the command above. Docker Compose is a better method, just like for other usual projects.

Here are the official instructions.

Create a new directory

Put the contents of the file below in a file called compose.yaml

Run docker compose up -d in that directory

Done! Point your client at your host's name/IP address and port 25565.

# docker.yaml
services:
  mc:
    image: itzg/minecraft-server:latest
    pull_policy: daily
    tty: true
    stdin_open: true
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
    volumes:
      # attach the relative directory 'data' to the container's /data path
      - ./data:/data

To apply changes made to the compose file, just run docker compose up -d again.

Follow the logs of the container using docker compose logs -f, check on the status with docker compose ps, and stop the container using docker compose stop.

If you are new to Docker, volumes may be a little confusing. Well, they are actually quite simple. One possible directory structure looks like this:

Your-MC-Server-Folder
├── data
│   ├── config
│   ├── eula.txt
│   ├── kubejs
│   ├── mods
│   ├── server.properties
│   └── world
└── docker-compose.yml

The data folder inside Your-MC-Server-Folder is where you put all the mods and world data. Of course, you can also run Docker Compose first and let the container generate the data by itself, or just move your existing data into data.

Loader and mods

Starting a modded server is also possible by changing the variables in compose.yaml. Here is my own configuration. You can use SetupMC to help generate yours.

services:
  mc:
    image: itzg/minecraft-server:latest
    tty: true
    stdin_open: true
    ports:
      - "25565:25565"
      - "24454:24454/udp"
    environment:
      EULA: "TRUE"
      TYPE: "NEOFORGE"
      VERSION: "1.21.1"
      INIT_MEMORY: "4G"
      MAX_MEMORY: "12G"
      MOTD: "A Minecraft Server"
      TZ: "Asia/Tokyo"
      DIFFICULTY: "hard"
    volumes:
      - "./data:/data"

Btw, port 24454/udp is open because of the mod “Simple Voice Chat.” In this situation, you also need to change the IP to 0.0.0.0 in the Simple Voice Chat config.

And…

Have fun!

SHIINAYANE (en)

I Turned My AI Workflow into Code. Then I Tore It Apart.

The scroll position that kept getting more complete

The process worked exactly as designed

I nearly turned the correction into another process

What happens to the two Skills?

No new answer yet

I Turned My AI Workflow into Code

Copying BiliKit's AGENTS.md did not work

It ended up looking more like a compiler

Why there are two Skills

A Skill also needs to know when to stay out

Keeping SKILL.md small

How far should Apple validation go?

Even the installer needs guardrails

Vague rules became harder to keep

The Skills need tests too

AI Made Code Cheap. It Made Engineering More Expensive.

The code usually compiled

Moving the context into the repository

Building one real path at a time

Five changed lines can still be red

Tests only prove what they observe

The workflow I ended up with

What's New in Swift — WWDC26 Notes

Everyday Swift

Optional parentheses around some and any

weak let

~Sendable

Task errors now get a warning

Async work in defer

Two memberwise initializers

@diagnose

Module selectors with ::

Library updates

Standard library

Swift Testing

Subprocess 1.0

Foundation ProgressManager

Swift outside Apple platforms

anyAppleOS

@C

Java and Android

WebAssembly

Embedded Swift

Editor support

Performance and ownership

Optimizer hints

Ownership in the standard library

New low-overhead types

Configuration Is Easy; Maintenance Is the Work

What drift looks like

A health check should only make drift visible

The 30-day test

Do not turn maintenance into another system

One Architecture, Many Languages

Node.js / TypeScript

Java

Swift / iOS

Rust

Go

Ruby

What stays consistent across languages

When to Let the Official Tool Win

What counts as a sovereign tool

Applying it to the languages I use

mise can be a proxy

The answers can change

Making mise and uv Agree on Python

Finding the other Python

Interpreter, virtual environment, and cache

Restricting uv to system Python

Existing projects can fail after the change

Small scripts do not need full projects

The Brewfile Compromise: Eventual Consistency for Mac Apps

Why I tolerate drift here

Choosing an installation channel

One file for the intended state

How I reconcile it

Letting an agent audit the list

Optional parentheses around `some` and `any`

`weak let`

`~Sendable`

Async work in `defer`

`@diagnose`

Module selectors with `::`

Foundation `ProgressManager`

`anyAppleOS`

`@C`

`mise` can be a proxy

`map`, `compactMap`, and `flatMap`