Build, verify, and release Hidden Bar. Assumes current Xcode on macOS 13+.
# CI-style build, no signing required
xcodebuild -project 'Hidden Bar.xcodeproj' -scheme 'Hidden Bar' \
-configuration Debug CODE_SIGNING_ALLOWED=NO build
# runnable local build (uses your Apple Development identity)
xcodebuild -project 'Hidden Bar.xcodeproj' -scheme 'Hidden Bar' \
-configuration Debug buildBoth must exit 0 with no MACOSX_DEPLOYMENT_TARGET override; the floor is
13.0 in the project file. The single expected warning is the deliberately
deprecated SMLoginItemSetEnabled(false) call that cleans up legacy installs.
The repo has no unit-test infrastructure; behavior is verified against the real menu bar. Two building blocks make that scriptable:
- Truth signal: the separator's AX size.
osascript -e 'tell application "System Events" to tell process "Hidden Bar" to get size of menu bar item 2 of menu bar 2'reads ~20pt expanded vs ~2x-screen-width collapsed. Item 1 is the arrow. - Real clicks, not AXPress:
AXPresson the arrow is a no-op because the action handler readsNSApp.currentEvent(nil under assistive synthesis; known accessibility defect). Post realCGEventmouse clicks at the arrow's AX-reported coordinates instead.
Standard checks before any release:
- expand/collapse toggle flips the separator size both ways;
- with
numberOfSecondForAutoHideset to 3, an expanded bar survives 2x the window while the pointer is parked in the menubar band, collapses within the window once the pointer leaves, and collapses normally if the pointer never entered; hoverToExpandoff: no monitor log line, hover does nothing; on (the Preferences checkbox, no relaunch): dwell expands (synthesize amouseMovedstream: cursor warping alone fires no events);- autostart pref on ->
AutoStart: SMAppService.mainApp.status = 1on stderr; off ->= 0(run the binary directly to capture stderr); - localization tables stay parseable:
plutil -lint hidden/*.lproj/*.strings.
A Debug build listens for the distributed notification
com.dwarvesv.minimalbar.debug.command (userInfo command, argument, out;
StatusBarController.handleDebugCommand). scripts/hb-cmd is the one sender,
so nothing is posted by hand and no key or pointer input is involved:
scripts/hb-cmd <command> [argument] [--out path] [--timeout seconds] [--dry-run]- It posts through JXA (
osascript -l JavaScript,NSDistributedNotificationCenter). - With
--outit waits (default 15 s) for the app to write that file, newer than the call, and exits 1 on timeout; exit 2 is a usage or osascript error. A Release build has no hooks and ignores the post, so it times out. --dry-runposts nothing: it prints what it would send and still runs the wait, which is how the argument parsing and the timeout path are tested without an app.dump-statewrites the engine and preference state;dump-inventorywrites the menu-bar app catalog (MenuBarItemCatalog: bundle id, name, section, first-seen time, running state, and the arrivals of the latest read) as JSON toout.- A feature adds its own commands as new cases in
handleDebugCommand, prefixed by the feature name. - Run it only against a Debug build you own. An unknown command is logged and, with
--out, answered with the state dump.
When testing on a machine that runs Hidden Bar daily: do not swap by hand. Build the Release-Direct
app signed with the Developer ID team, then scripts/install-local.sh --app "Hidden Bar.app" (it
backs up the prefs, quits the app, keeps the installed app aside and relaunches), test, and put
everything back with scripts/install-local.sh --restore (see the next section).
scripts/install-local.sh [--host ALIAS [--when-online]] [--check-only] ZIP|--app PATH|--restore [RUN_DIR]
installs a Hidden-Bar-vX.Y.Z-macos.zip into /Applications; --host goes over mini-run, and
--when-online waits (bounded, --wait-max) for a host that is offline. It refuses a zip that
is not signed by team W777S7V8TN or that Gatekeeper does not call Notarized Developer ID,
before touching /Applications. It then backs up the prefs domain and moves the replaced app
into ~/Library/Application Support/HiddenBar-backup/<stamp>/ (nothing is deleted), installs with
ditto, relaunches, and prints a before/after table: version, CDHash, Gatekeeper, and the System
Events login items named "Hidden Bar", which must all point at /Applications/Hidden Bar.app
(exit 4 flags a stray; remove it by hand). --check-only verifies the zip and shows what is
installed now, changing nothing.
--app PATH installs a built Hidden Bar.app directory instead (test a branch build against the
real app). It needs the same Developer ID team as the installed app, skips the notarization
requirement and says so in the table (signature, bundle id and team are still checked); over --host
the app travels as a zip. Every run writes meta.txt into its backup folder with the CDHash of the
app it set aside. --restore [RUN_DIR] (latest run when omitted) quits the app, moves the current
app into the run folder as Hidden Bar.replaced.<stamp>.app, moves the backed-up app back, runs
defaults import on the saved prefs (the replaced prefs stay as prefs.replaced.<stamp>.plist),
relaunches, and checks the restored CDHash equals the recorded one (exit 4 if not). Nothing is
deleted. Tests: bash scripts/test-install-local.sh (fixtures only, never
the real /Applications). Never judge arrow or hiding behaviour on a copy outside /Applications.
-
Verify the stack: every PR reviewed, builds green, behavioral checks above run.
-
Bump
MARKETING_VERSIONandCURRENT_PROJECT_VERSIONin the project file (every occurrence: the App Store target's four configurations plus the Direct target's four;grep -c MARKETING_VERSIONmust match the count you edited). -
Archive the GitHub build with the Hidden Bar scheme (
Release-Direct; builds the Hidden Bar Direct target), then notarize (Developer ID), staple, zip, and publish a GitHub release with notes listing closed issues. The Hidden Bar App Store scheme archivesRelease, the sandboxed App Store build, which cannot hide on macOS 27. v1.11 shipped that build to GitHub by mistake. Before zipping, confirm the app is unsandboxed:codesign -d --entitlements - 'Hidden Bar.app' | grep app-sandbox # must print nothing
The target signs automatically for development, so a plain archive fails with "conflicting provisioning settings". Archive with manual Developer ID signing, then export with
methoddeveloper-id(signingStylemanual,signingCertificate"Developer ID Application"); the export re-signs Sparkle's XPC services,AutoupdateandUpdater.appwith hardened runtime and a timestamp:xcodebuild archive -project 'Hidden Bar.xcodeproj' -scheme 'Hidden Bar' \ -configuration Release-Direct -archivePath build/HiddenBar.xcarchive \ CODE_SIGN_STYLE=Manual CODE_SIGN_IDENTITY='Developer ID Application' \ DEVELOPMENT_TEAM=W777S7V8TN OTHER_CODE_SIGN_FLAGS=--timestamp
-
App Store (separate lane, Hidden Bar App Store scheme): the MAS listing has lagged GitHub since v1.8 (issues #281/#202); decide deliberately whether a release goes there too.
-
Homebrew cask (
brew install --cask hiddenbar) follows the GitHub release artifact; notarization matters (issue #219). -
Sparkle appcast (direct build only, see below): sign the notarized zip, add the appcast entry, upload
appcast.xmlto the release. -
Before any public release after the SMAppService migration: one upgrade-path run from a launcher-era build (v1.9 or older) verifying System Settings shows no ghost LauncherApplication login item.
The direct build self-updates through Sparkle 2 (SUFeedURL in
hidden/Info-Direct.plist is
https://github.com/consolelabs/hidden/releases/latest/download/appcast.xml, so
the appcast must be an asset of the latest release). The private EdDSA key
lives in 1Password (dfoundation-prod, item "Hidden Bar Sparkle EdDSA private
key"); only the public key (SUPublicEDKey) is in the repo. Losing the key
means no installed copy can ever verify another update, so never regenerate it.
Sparkle's sign_update and generate_appcast come from the Sparkle release
tarball matching the pinned package version (2.10.1, Sparkle-<ver>.tar.xz
under bin/). Run from a folder that holds only the zip(s) to publish:
# 1. zip the stapled app (keep the name stable: Hidden-Bar-v<version>-macos.zip,
# the asset name the Homebrew cask URL expects)
ditto -c -k --sequesterRsrc --keepParent 'Hidden Bar.app' Hidden-Bar-v1.12-macos.zip
# 2. EdDSA signature (key streamed from 1Password, never written to disk)
sign_update --ed-key-file <(op read 'op://dfoundation-prod/Hidden Bar Sparkle EdDSA private key/password') Hidden-Bar-v1.12-macos.zip
# prints: sparkle:edSignature="..." length="..."
# 3. appcast entry (reads the same key; run over a folder holding the new zip
# plus the previous appcast.xml so history is kept; skip the download on
# the first Sparkle release)
gh release download --pattern appcast.xml -R consolelabs/hidden # from the previous release
generate_appcast --ed-key-file <(op read 'op://dfoundation-prod/Hidden Bar Sparkle EdDSA private key/password') \
--download-url-prefix 'https://github.com/consolelabs/hidden/releases/download/v1.12/' \
--link 'https://github.com/consolelabs/hidden' .
# 4. publish: the zip and appcast.xml are both release assets
gh release upload v1.12 Hidden-Bar-v1.12-macos.zip appcast.xml --clobber -R consolelabs/hidden
# 5. also upload a copy of the zip named Hidden-Bar-macos.zip, so
# releases/latest/download/Hidden-Bar-macos.zip stays stable (a byte-identical
# copy; the appcast and the Homebrew cask keep using the versioned name)
cp Hidden-Bar-v1.12-macos.zip Hidden-Bar-macos.zip
gh release upload v1.12 Hidden-Bar-macos.zip --clobber -R consolelabs/hiddenCheck before announcing: curl -sIL https://github.com/consolelabs/hidden/releases/latest/download/appcast.xml
ends in 200, and the entry's sparkle:version equals CURRENT_PROJECT_VERSION
(Sparkle compares that, not the marketing version, so it must increase every
release). Because latest follows the newest published release, publish the
release as a draft first, upload assets, then publish.
Two targets share the sources. Hidden Bar Direct (scheme Hidden Bar,
Debug-Direct/Release-Direct) is unsandboxed, defines HIDDENBAR_SPARKLE,
uses hidden/Info-Direct.plist, and is the only one that links and embeds
Sparkle. Hidden Bar (scheme Hidden Bar App Store, Debug/Release) has
no Sparkle package, flag, or Info.plist keys. SwiftPM cannot link a package
per configuration, which is why this is two targets, not one. The unused
combinations (App Store target in *-Direct, Direct target in Debug/Release)
are named Hidden Bar (unused) on purpose: the test bundles resolve their
host app by product path, and two targets producing Hidden Bar.app in one
configuration break build-for-testing. After archiving the App Store build:
otool -L 'Hidden Bar.app/Contents/MacOS/Hidden Bar' | grep -c Sparkle # must print 0Feature stacks land as chained PRs (develop <- A <- B). Merge the base PR
first, then retarget the next PR's base to develop BEFORE merging it;
deleting a merged branch auto-closes dependents otherwise.
The live clusters and their code areas are documented at the end of
ARCHITECTURE.md: notch, macOS 27
mechanism break, and pointer-vs-open-menu limits. Memory reports (#361 et al.)
have so far not reproduced as leaks (constraint-leak fix landed; leaks clean
over toggle stress); re-check with a 24h+ uptime footprint sample before
chasing further.