feat: a Swift client for Zero (iOS and macOS)

.agents/setup

@@ -7,7 +7,8 @@ export DEBIAN_FRONTEND=noninteractive
 
 echo '==> Checking native build prerequisites'
 missing=()
-for package in build-essential python3 pkg-config curl ca-certificates xz-utils; do
+# postgresql backs the Swift end-to-end tests (packages/zero-conformance/src/e2e).
+for package in build-essential python3 pkg-config curl ca-certificates xz-utils postgresql; do
   if [[ "$(dpkg-query -W -f='${Status}' "$package" 2>/dev/null || true)" != 'install ok installed' ]]; then
     missing+=("$package")
   fi
@@ -17,6 +18,26 @@ if ((${#missing[@]})); then
   time sudo apt-get install -y "${missing[@]}"
 fi
 
+echo '==> Installing the Swift toolchain for swift/'
+swift_version='6.2.4'
+if [[ "$(/opt/swift/usr/bin/swift --version 2>/dev/null || true)" != *"swift-${swift_version}-RELEASE"* ]]; then
+  time sudo apt-get update
+  time sudo apt-get install -y binutils-gold libicu-dev libcurl4-openssl-dev \
+    libedit-dev libsqlite3-dev libncurses-dev libpython3-dev libxml2-dev \
+    tzdata uuid-dev gnupg2 libstdc++-12-dev zlib1g-dev
+  swift_tmp="$(mktemp -d)"
+  time curl -sSfL -o "$swift_tmp/swift.tar.gz" \
+    "https://download.swift.org/swift-${swift_version}-release/debian12/swift-${swift_version}-RELEASE/swift-${swift_version}-RELEASE-debian12.tar.gz"
+  sudo rm -rf /opt/swift
+  sudo mkdir -p /opt/swift
+  sudo tar -xzf "$swift_tmp/swift.tar.gz" -C /opt/swift --strip-components=1
+  rm -rf "$swift_tmp"
+fi
+for tool in swift swiftc sourcekit-lsp docc; do
+  sudo ln -sf "/opt/swift/usr/bin/$tool" "/usr/local/bin/$tool"
+done
+swift --version
+
 echo '==> Selecting the repository Node and pnpm versions'
 node_version="$(tr -d '[:space:]' < .nvmrc)"
 if [[ "$(node -p 'process.versions.node')" != "$node_version" && "$(node -p 'process.versions.node')" != "$node_version".* ]]; then
@@ -40,6 +61,14 @@ pnpm --version
 PATH="${PNPM_HOME:-$HOME/.local/share/pnpm}/bin:$PATH" \
   pnpm config set --global verify-deps-before-run false
 
+# zero-cache runs from source only on Node 24 (`using`), which the Swift
+# end-to-end server needs; the .nvmrc Node stays the default.
+echo '==> Installing Node 24 for zero-cache into ~/.local/node24'
+if [[ "$("$HOME/.local/node24/bin/node" --version 2>/dev/null || true)" != v24.* ]]; then
+  time N_PREFIX="$HOME/.local/node24" n install 24
+fi
+"$HOME/.local/node24/bin/node" --version
+
 echo '==> Installing workspace dependencies from the lockfile'
 time pnpm install --frozen-lockfile
 

.changeset/README.md

@@ -0,0 +1,17 @@
+# Changesets
+
+Changesets version the Swift client: the `zero-swift` npm package
+(`packages/zero-swift-cli`) and the Swift package (`swift/`), which share one
+version. Upstream Zero's packages are released separately and are ignored here.
+
+To release a change to either, add a changeset for `zero-swift`:
+
+```sh
+pnpm changeset
+```
+
+On `main`, `.github/workflows/swift-release.yml` keeps a "Version Packages" pull
+request open with the pending version and changelog. Merging it sets the
+version in `packages/zero-swift-cli/package.json` and `swift/VERSION`, and the
+workflow then publishes the npm package and tags the SwiftPM mirror after
+approval in the `swift-release` environment.

.changeset/config.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@4.0.1/schema.json",
+  "baseBranch": "main",
+  "access": "public",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "format": "oxfmt",
+  "ignore": ["@rocicorp/zero-events", "replicache", "otel-proxy"],
+  "privatePackages": {"version": false, "tag": false}
+}

.github/actions/playwright-install/action.yml

@@ -6,14 +6,18 @@ runs:
   steps:
     - name: Get Playwright version
       id: playwright-version
-      run: echo "version=$(pnpm exec playwright --version | awk '{print $NF}')" >> "$GITHUB_OUTPUT"
+      # The OS release too: browsers built for one Ubuntu release don't run
+      # on the next, which ubuntu-latest moves to.
+      run: |
+        echo "version=$(pnpm exec playwright --version | awk '{print $NF}')" >> "$GITHUB_OUTPUT"
+        echo "os=$(. /etc/os-release && echo "$ID-$VERSION_ID")" >> "$GITHUB_OUTPUT"
       shell: bash
     - name: Cache Playwright browsers
       id: playwright-cache
       uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
       with:
         path: ~/.cache/ms-playwright
-        key: playwright-${{ runner.os }}-${{ runner.arch }}-${{ steps.playwright-version.outputs.version }}
+        key: playwright-${{ runner.os }}-${{ steps.playwright-version.outputs.os }}-${{ runner.arch }}-${{ steps.playwright-version.outputs.version }}
     - name: Install Playwright browsers and system deps
       if: steps.playwright-cache.outputs.cache-hit != 'true'
       run: timeout -k 30s 20m pnpm exec playwright install --with-deps

.github/workflows/public-js.yml

@@ -79,8 +79,9 @@ jobs:
   test:
     name: Public Test
     if: github.repository == 'rocicorp/mono' || github.repository == 'rocicorp/mono-internal' || github.repository == 'wevm/zero'
-    # See Public Checks. x64, since this runs WebKit and Firefox too.
-    runs-on: ${{ github.repository == 'rocicorp/mono-internal' && 'ubuntu-x64-8-core' || 'ubuntu-latest' }}
+    # See Public Checks. x64, since this runs WebKit and Firefox too. Ubuntu
+    # 24.04, not ubuntu-latest: Playwright 1.60 has no browsers for 26.04.
+    runs-on: ${{ github.repository == 'rocicorp/mono-internal' && 'ubuntu-x64-8-core' || 'ubuntu-24.04' }}
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:

.github/workflows/swift-macos.yml

@@ -0,0 +1,81 @@
+name: Swift (macOS)
+
+# The Apple-only layer (ZeroUI, the URLSession transport) and iOS simulator
+# tests. Path-filtered because macOS runners are slow to start.
+
+on:
+  push:
+    # swift-client is the development branch until the client lands on main.
+    branches: [main, swift-client]
+    paths:
+      - 'swift/**'
+      - 'packages/zero-conformance/**'
+      - 'apps/zbugs-swift/**'
+      - '.github/workflows/swift-macos.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'swift/**'
+      - 'packages/zero-conformance/**'
+      - 'apps/zbugs-swift/**'
+      - '.github/workflows/swift-macos.yml'
+
+concurrency:
+  group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  macos:
+    name: Swift (macOS)
+    runs-on: macos-26
+    timeout-minutes: 45
+    defaults:
+      run:
+        working-directory: swift
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - run: swift --version
+      - name: Build and test (macOS)
+        run: swift test
+      - name: Docs
+        run: scripts/docs.sh
+      - name: Test (iOS Simulator)
+        run: |
+          device="$(xcrun simctl list devices available -j |
+            python3 -c 'import json,sys; d=json.load(sys.stdin)["devices"]; print(next(x["udid"] for k,v in d.items() if "iOS" in k for x in v if x["name"].startswith("iPhone")))')"
+          xcodebuild test -scheme Zero-Package -destination "id=$device" -skipPackagePluginValidation
+
+  zbugs:
+    name: zbugs app (iOS and macOS)
+    runs-on: macos-26
+    timeout-minutes: 45
+    defaults:
+      run:
+        working-directory: apps/zbugs-swift
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      # The drift test again, and ZBugsUI (empty on Linux) for macOS.
+      - name: Build and test (macOS)
+        run: swift test
+      - name: Generate the Xcode project
+        working-directory: apps/zbugs-swift/App
+        run: brew install xcodegen && xcodegen generate
+      - name: Build the app (iOS Simulator)
+        working-directory: apps/zbugs-swift/App
+        run: >-
+          xcodebuild build -project ZBugs.xcodeproj -scheme ZBugsApp
+          -destination 'generic/platform=iOS Simulator'
+          -skipPackagePluginValidation CODE_SIGNING_ALLOWED=NO
+      - name: Build the app (macOS)
+        working-directory: apps/zbugs-swift/App
+        run: >-
+          xcodebuild build -project ZBugs.xcodeproj -scheme ZBugsApp
+          -destination 'generic/platform=macOS'
+          -skipPackagePluginValidation CODE_SIGNING_ALLOWED=NO

.github/workflows/swift-release.yml

@@ -0,0 +1,167 @@
+name: Swift Release
+
+# Releases the Swift client, versioned with Changesets (see .changeset/README.md).
+# The zero-swift npm package (packages/zero-swift-cli) and the Swift package
+# (swift/) share one version, kept in step by `pnpm changeset:version`.
+#
+# On each push to main:
+# - With pending changesets, opens or updates the "Version Packages" PR.
+# - Otherwise, if the version in swift/VERSION isn't released yet, after
+#   approval in the swift-release environment:
+#   - publishes swift/ to the SwiftPM mirror (wevm/zero-swift) and tags the
+#     version there. SwiftPM needs Package.swift at a repository root and
+#     clones whole repositories, so consumers install from the mirror.
+#   - publishes the zero-swift CLI to npm with trusted publishing.
+# Each step is skipped when its release already exists, so a failed run can be
+# rerun.
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: swift-release
+  cancel-in-progress: false
+
+jobs:
+  version:
+    name: Version PR
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    outputs:
+      has-changesets: ${{ steps.changesets.outputs.has-changesets }}
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+        with:
+          version: 11.11.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version-file: .nvmrc
+          package-manager-cache: false
+      - run: pnpm install --frozen-lockfile
+      - id: changesets
+        uses: changesets/action@ae32849d5ba541f9ae29e40e22a623bc13562f51 # v2.1.2
+        with:
+          version-script: pnpm changeset:version
+          commit-message: 'chore(zero-swift): version packages'
+          pr-title: 'chore(zero-swift): version packages'
+
+  plan:
+    name: Plan release
+    runs-on: ubuntu-latest
+    needs: version
+    if: needs.version.outputs.has-changesets == 'false'
+    outputs:
+      version: ${{ steps.plan.outputs.version }}
+      mirror: ${{ steps.plan.outputs.mirror }}
+      npm: ${{ steps.plan.outputs.npm }}
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+          sparse-checkout: |
+            swift/VERSION
+            packages/zero-swift-cli/package.json
+          sparse-checkout-cone-mode: false
+      - id: plan
+        run: |
+          set -euo pipefail
+          version="$(tr -d '[:space:]' < swift/VERSION)"
+          package="$(jq -r .version packages/zero-swift-cli/package.json)"
+          if [ "$package" != "$version" ]; then
+            echo "packages/zero-swift-cli is $package but swift/VERSION is $version." >&2
+            exit 1
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          if git ls-remote --exit-code --tags https://github.com/wevm/zero-swift.git "refs/tags/$version" >/dev/null; then
+            echo "mirror=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "mirror=true" >> "$GITHUB_OUTPUT"
+          fi
+          if npm view "zero-swift@$version" version >/dev/null 2>&1; then
+            echo "npm=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "npm=true" >> "$GITHUB_OUTPUT"
+          fi
+
+  mirror:
+    name: Publish mirror
+    runs-on: ubuntu-latest
+    needs: plan
+    if: needs.plan.outputs.mirror == 'true'
+    environment: swift-release
+    env:
+      MIRROR_TOKEN: ${{ secrets.ZERO_SWIFT_MIRROR_TOKEN }}
+      MIRROR_REPO: wevm/zero-swift
+      VERSION: ${{ needs.plan.outputs.version }}
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Split and push
+        run: |
+          set -euo pipefail
+          git subtree split --prefix=swift -b mirror
+          remote="https://x-access-token:${MIRROR_TOKEN}@github.com/${MIRROR_REPO}.git"
+          git push "$remote" mirror:main
+          git tag "$VERSION" mirror
+          git push "$remote" "refs/tags/$VERSION"
+
+  npm-build:
+    name: Build npm package
+    runs-on: ubuntu-latest
+    needs: plan
+    if: needs.plan.outputs.npm == 'true'
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+        with:
+          version: 11.11.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version-file: .nvmrc
+          package-manager-cache: false
+      - run: pnpm install --frozen-lockfile
+      - name: Build and pack
+        run: |
+          pnpm --filter zero-swift build
+          pnpm --filter zero-swift pack --pack-destination "$GITHUB_WORKSPACE/dist/npm"
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: zero-swift-npm
+          path: dist/npm/*.tgz
+          if-no-files-found: error
+
+  npm-publish:
+    name: Publish npm package
+    runs-on: ubuntu-latest
+    needs: [plan, npm-build]
+    environment: swift-release
+    permissions:
+      contents: read
+      id-token: write # For npm trusted publishing.
+    env:
+      VERSION: ${{ needs.plan.outputs.version }}
+    steps:
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24.x
+          registry-url: 'https://registry.npmjs.org'
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: zero-swift-npm
+          path: dist/npm
+      - name: Publish
+        run: npm publish "dist/npm/zero-swift-$VERSION.tgz" --provenance --access public