Sync fork to upstream 0.31.1 + preserve color/separator (May 2026)

.agents/skills/release-codexbar/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: release-codexbar
+description: "CodexBar release: versioning, notarization, appcast, Homebrew, post-release bump."
+---
+
+# CodexBar Release
+
+Use for releasing signed/notarized macOS apps, especially repos with Sparkle appcasts and Homebrew casks.
+
+## Start
+
+1. Work from the app repo unless asked otherwise.
+2. Check repo state, current version, latest tag/release, and release docs/scripts.
+3. Confirm `CHANGELOG.md` is complete, user-facing, deduped, and dated for the release.
+4. Prefer the repo release script; patch small script/test blockers instead of bypassing the release path.
+5. Never print key material. Keep 1Password references and local key paths as references only.
+6. Load `$release-private` if it exists before resolving Peter-owned credential locators.
+
+## Key Material
+
+Use `$one-password` for secret handling. `op` only in tmux/persistent shell; no broad `env`, `set`, `export -p`, or secret scans.
+
+Known App Store Connect shape:
+
+- fields: `private_key_p8`, `key_id`, `issuer_id`
+- keep all three fields from the same 1Password item; do not mix with stale values from `~/.profile`
+- resolve Peter-owned item refs from `$release-private`
+
+Known Sparkle key:
+
+- resolve the private key file from `$release-private`
+- pass as `SPARKLE_PRIVATE_KEY_FILE`
+
+Safe env file pattern:
+
+```text
+APP_STORE_CONNECT_API_KEY_P8=<1Password ref from release-private>
+APP_STORE_CONNECT_KEY_ID=<1Password ref from release-private>
+APP_STORE_CONNECT_ISSUER_ID=<1Password ref from release-private>
+SPARKLE_PRIVATE_KEY_FILE=<path from release-private>
+```
+
+Run with `op run --account my.1password.com --env-file <file> -- <script>`, then delete the temp env file.
+
+## CodexBar
+
+Paths:
+
+- repo: `~/Projects/codexbar`
+- release script: `Scripts/release.sh`
+- signing/notarization: `Scripts/sign-and-notarize.sh`
+- appcast: `Scripts/make_appcast.sh`, `appcast.xml`
+- release assets: `CodexBar-macos-universal-<version>.zip`, `CodexBar-macos-universal-<version>.dSYM.zip`
+- packaged app: `CodexBar.app`
+- version file: `version.env`
+- changelog: `CHANGELOG.md`
+- Homebrew tap: `~/Projects/homebrew-tap`
+- cask: `~/Projects/homebrew-tap/Casks/codexbar.rb`
+- formula: `~/Projects/homebrew-tap/Formula/codexbar.rb`
+- CLI release workflow: `.github/workflows/release-cli.yml`
+
+Normal release:
+
+```bash
+tmux new-session -d -s codexbar-release 'op run --account my.1password.com --env-file /tmp/codexbar-release-op.env -- Scripts/release.sh'
+tmux attach -t codexbar-release
+```
+
+If notarization fails with `401 Unauthenticated`, rerun using all three App Store Connect fields from the 1Password item above. Mismatched `key_id` / `issuer_id` from `~/.profile` can cause this.
+
+If widget metadata generation times out, `CODEXBAR_WIDGET_METADATA_TIMEOUT_SECONDS=600` is a known-good floor.
+
+CodexBar CLI tarballs are not produced by `Scripts/release.sh` itself. The GitHub release event triggers `.github/workflows/release-cli.yml`, which builds and uploads:
+
+- `CodexBarCLI-v<version>-macos-arm64.tar.gz`
+- `CodexBarCLI-v<version>-macos-x86_64.tar.gz`
+- `CodexBarCLI-v<version>-linux-aarch64.tar.gz`
+- `CodexBarCLI-v<version>-linux-x86_64.tar.gz`
+- matching `.sha256` files
+
+If the workflow fails only in `update-homebrew-tap` with GitHub API rate limiting, the CLI assets may already be uploaded. Verify assets live, then update `Formula/codexbar.rb` manually from the tarball checksums.
+
+## Verify
+
+Release is not done until the published chain checks out:
+
+```bash
+gh release view v<VERSION> --json tagName,name,isDraft,isPrerelease,url,assets,body
+Scripts/check-release-assets.sh v<VERSION>
+python3 - <<'PY'
+import xml.etree.ElementTree as ET
+ns={'sparkle':'http://www.andymatuschak.org/xml-namespaces/sparkle'}
+root=ET.parse('appcast.xml').getroot()
+item=root.find('channel').find('item')
+enc=item.find('enclosure')
+print(item.findtext('title'))
+print(item.findtext('sparkle:version', namespaces=ns))
+print(item.findtext('sparkle:shortVersionString', namespaces=ns))
+print(enc.attrib.get('url'))
+print(enc.attrib.get('length'))
+print(bool(enc.attrib.get('{http://www.andymatuschak.org/xml-namespaces/sparkle}edSignature')))
+PY
+codesign --verify --deep --strict --verbose=2 CodexBar.app
+spctl --assess --type execute --verbose CodexBar.app
+```
+
+For Homebrew:
+
+```bash
+shasum -a 256 CodexBar-macos-universal-<VERSION>.zip
+cd /Users/steipete/Projects/homebrew-tap
+python3 .github/scripts/update_formula.py --formula codexbar --tag v<VERSION> --repository steipete/CodexBar --artifact-template 'CodexBarCLI-{tag}-{target}.tar.gz' --target-aliases 'darwin_arm64=macos-arm64,darwin_amd64=macos-x86_64,linux_arm64=linux-aarch64,linux_amd64=linux-x86_64'
+brew fetch --cask --force --retry codexbar
+brew fetch --formula --force --retry steipete/tap/codexbar
+```
+
+Update the cask when app zip assets exist. Update the formula only when standalone CLI tarballs for that version exist.
+
+Tap audit can be noisy from unrelated formulae; keep evidence specific to the app cask.
+
+## Closeout
+
+1. Create/push tag and GitHub release through the release script.
+2. Verify appcast points to the new GitHub release asset with signature and length.
+3. Update/push the Homebrew cask if the app zip changed.
+4. Bump the app repo to next patch `Unreleased`:
+   - `version.env`: next `MARKETING_VERSION`, next `BUILD_NUMBER`
+   - `CHANGELOG.md`: top `## <next> — Unreleased`
+5. Commit, push, then pull `--ff-only`.
+6. Restart the local app from the packaged bundle and verify the running bundle version.
+7. Check no release/notary/op temp sessions or temp env files remain.
+
+CodexBar restart:
+
+```bash
+pkill -x CodexBar || pkill -f CodexBar.app || true
+cd "$(git rev-parse --show-toplevel)"
+open -n CodexBar.app
+/usr/libexec/PlistBuddy -c 'Print :CFBundleShortVersionString' CodexBar.app/Contents/Info.plist
+/usr/libexec/PlistBuddy -c 'Print :CFBundleVersion' CodexBar.app/Contents/Info.plist
+```

.github/workflows/ci.yml

@@ -2,12 +2,17 @@ name: CI
 
 on:
   push:
-    branches: ["*"]
+    branches: ["**"]
   pull_request:
 
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   lint-build-test:
-    runs-on: macos-latest
+    runs-on: macos-15-intel
+    timeout-minutes: 70
     steps:
       - uses: actions/checkout@v6
 
@@ -36,9 +41,12 @@ jobs:
         run: ./Scripts/lint.sh lint
 
       - name: Swift Test
-        run: swift test --no-parallel
+        timeout-minutes: 60
+        run: |
+          python3 Scripts/ci_swift_test_by_suite.py --group-size 1 --timeout 120
 
   build-linux-cli:
+    timeout-minutes: 20
     strategy:
       fail-fast: false
       matrix:
@@ -57,11 +65,39 @@ jobs:
           uname -a
           uname -m
 
-      - name: Setup Swift 6.2.1
-        uses: swift-actions/setup-swift@v3
-        with:
-          swift-version: "6.2.1"
-          skip-verify-signature: true
+      - name: Install Swift 6.2.1 via swiftly
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if ! command -v gpg >/dev/null 2>&1; then
+            sudo apt-get update
+            sudo apt-get install -y ca-certificates gpg
+          fi
+
+          SWIFTLY_ARCH="$(uname -m)"
+          SWIFTLY_HOME_DIR="$HOME/.local/share/swiftly"
+          SWIFTLY_BIN_DIR="$HOME/.local/bin"
+          POST_INSTALL_SCRIPT="$(mktemp)"
+
+          mkdir -p "$SWIFTLY_BIN_DIR"
+          curl -fsSL "https://download.swift.org/swiftly/linux/swiftly-${SWIFTLY_ARCH}.tar.gz" -o /tmp/swiftly.tar.gz
+          tar -xzf /tmp/swiftly.tar.gz -C /tmp
+          /tmp/swiftly init --assume-yes --skip-install
+
+          . "$SWIFTLY_HOME_DIR/env.sh"
+          echo "$SWIFTLY_BIN_DIR" >> "$GITHUB_PATH"
+          echo "SWIFTLY_HOME_DIR=$SWIFTLY_HOME_DIR" >> "$GITHUB_ENV"
+          echo "SWIFTLY_BIN_DIR=$SWIFTLY_BIN_DIR" >> "$GITHUB_ENV"
+
+          swiftly install 6.2.1 --use --assume-yes --post-install-file "$POST_INSTALL_SCRIPT"
+          if [[ -s "$POST_INSTALL_SCRIPT" ]]; then
+            sudo apt-get update
+            sudo bash "$POST_INSTALL_SCRIPT"
+          fi
+
+          hash -r
+          swift --version
 
       - name: Build CodexBarCLI (release, static Swift stdlib)
         run: swift build -c release --product CodexBarCLI --static-swift-stdlib