How to build, test, run, sign, and release Lerro. The architecture is in
architecture.md.
- An Apple silicon Mac with a macOS 26 SDK.
Package.swiftfixes the Swift tools version and deployment target. - Xcode command line tools:
xcode-select -p,swift --version. - Node.js 22.12 or later for
site/anddistribution/. - For releases: a Developer ID Application certificate, a
notarytoolKeychain profile, and the Sparkle Ed25519 private key in the login Keychain.
SwiftPM resource accessors need a standard app bundle, so run the app through the
script. A bare executable under .build/ lacks Dock identity, resources, and
signing, and is not a supported way to launch Lerro.
./script/build_and_run.sh # release build, assemble dist/Lerro.app, launch
./script/build_and_run.sh --debug # debug build
./script/build_and_run.sh --no-launch # build and verify only
./script/build_and_run.sh --verify # swift test, build, launch, confirm the process stays alive
./script/build_and_run.sh --logs # stream process logs
./script/build_and_run.sh --telemetry # stream logs for subsystem app.lerro.macThe script assembles dist/Lerro.app (SwiftPM resource bundles, Sparkle framework,
privacy manifest, terms, third-party licenses, app icon, Assets.car), converts
.strings and .stringsdict to binary property lists, checks the
resource accessor, arm64 slices, matching binary and dSYM UUIDs, plists, and the
code signature, then signs according to the signing mode. Running the script
terminates a running Lerro process before launching.
swift test # everything
swift test --filter AppSessionCoreFlowTests # one suite
swift test --filter LerroCoreTests # one target
swift test list # print the current test namesTargets: LerroCoreTests, LerroIntelligenceTests, LerroMacTests, LerroTests.
Tests use temporary directories and inert adapters. They never touch the real
Application Support folder, microphone, TCC, Accessibility, event taps, clipboard,
or login items. Swift Testing filters match the generated test names, so run
swift test list when a filter selects nothing.
Optional live check of the remote runtime against DeepSeek (reads
DEEPSEEK_API_KEY or a mode 0600 .env.deepseek.local, prints latency and pass
markers only):
./script/test_live_remote.shPython script tests (also run in CI):
python3 script/benchmark_contextual_dictation.py --validate
python3 script/test_contextual_benchmark.py
python3 script/test_capture_latency_report.pyFixture mode renders deterministic UI with in-memory repositories and inert
adapters. It does not start the microphone, request permissions, write to disk, or
use the network. Environment variables are read in
AppSession.swift,
AppDependencies.swift, and
InterfaceLocalization.swift.
./script/build_and_run.sh --debug --no-launch
open -F -n --env LERRO_FIXTURE_MODE=1 dist/Lerro.app
open -F -n --env LERRO_FIXTURE_MODE=1 --env LERRO_FIXTURE_DESTINATION=history dist/Lerro.app
open -F -n --env LERRO_FIXTURE_MODE=1 --env LERRO_FIXTURE_PRESENTATION=hud-recovery \
--env LERRO_FIXTURE_PANEL_ONLY=1 dist/Lerro.app| Variable | Values |
|---|---|
LERRO_FIXTURE_MODE |
1 enables fixture mode (required for the rest) |
LERRO_FIXTURE_DESTINATION |
home, history, dictionary, appTones |
LERRO_FIXTURE_PRESENTATION |
settings-general, settings-dictation, settings-ai, settings-ai-usage, settings-privacy, settings-about, prompt-dictate, prompt-translate, prompt-dictionaryLearning, menubar-panel, menubar-panel-listening, menubar-panel-permission, and hud- states (waiting, preparing-speech, recording, timer, hands-free, silent, dictating, translating, processing, processing-translation, delivered-fallback, delivered-fallback-balance, error, recovery, dictionary-learned) |
LERRO_FIXTURE_PANEL_ONLY |
1 shows only the panel (HUD and menu bar presentations) |
LERRO_FIXTURE_ONBOARDING, LERRO_FIXTURE_ONBOARDING_STEP |
1; step welcome, practice, ai, start |
LERRO_FIXTURE_AI |
connected (Key saved, balance 8.42 CNY), no-balance (Key saved, balance 0, account unavailable), off (no Key, AI cleanup off, Home shows the enable card). Default connected, or off when LERRO_FIXTURE_ONBOARDING=1. The fixture accepts any Key that starts with sk- and has at least 20 characters |
LERRO_FIXTURE_UPDATE_AVAILABLE |
1 shows the update indicator with version 1.9.1 without Sparkle |
LERRO_FIXTURE_APPEARANCE |
light, dark |
LERRO_FIXTURE_LANGUAGE |
en, zh-Hans |
LERRO_FIXTURE_REDUCE_MOTION, LERRO_FIXTURE_INCREASE_CONTRAST, LERRO_FIXTURE_REDUCE_TRANSPARENCY |
1 |
LERRO_FIXTURE_SCALE |
large scales the fixture to about 900 history entries and 40 dictionary entries |
LERRO_FIXTURE_BENCHMARK |
page-switch (switch time per page), focus (keyboard focus on hidden pages). Prints BENCHMARK lines to stdout and quits |
LERRO_FIXTURE_BENCHMARK_ROUNDS |
Page switch rounds, default 8; the first round is discarded |
For UI changes, check the main window at 1080x750 and 988x658, light and dark appearance, Increase Contrast, Reduce Transparency, Reduce Motion, and the affected HUD states and Settings tabs.
For main window, page, or AppSession changes, run the UI benchmark on a release
build. It uses the benchmark variables above, compares page switches with the
budget in performance.md, and restores the window frame
default afterwards:
./script/measure_ui_performance.sh [app_path] [runs]LERRO_SIGNING_MODE selects the mode. Resolution rules are in
script/signing_support.zsh.
| Mode | Identity | Use |
|---|---|---|
auto (default) |
Explicit LERRO_CODESIGN_IDENTITY, otherwise the first Apple Development identity, otherwise ad-hoc |
Local default |
ad-hoc |
- |
CI and machines without certificates |
development |
Apple Development: ... |
Stable code identity for repeated TCC testing |
developer-id |
Developer ID Application: ... |
Public releases; requires LERRO_NOTARY_PROFILE |
List identities with security find-identity -v -p codesigning. The script rejects
mismatched mode and identity combinations. Keep identity names, Team IDs, and
profile names in the maintainer's environment. They stay out of tracked files,
logs, and chat.
Release requires explicit approval from the maintainer, because it publishes to
Cloudflare and GitHub. Keep the source tree unchanged while it runs;
package_release.sh exits with code 75 when the tree changes during the build.
Maintainer labels live in config/maintainer.local.env (git-ignored; template in
config/maintainer.env.example).
-
Bump
CFBundleShortVersionStringandCFBundleVersioninconfig/Info.plist. Add the entry toCHANGELOG.mdand to the top ofreleasesinsite/src/data/releases.ts, and updatecurrentVersioninsite/src/site.ts. -
Commit.
-
Verify and package:
source config/maintainer.local.env LERRO_SIGNING_MODE=developer-id ./script/verify_release.shThis runs script lint, plist lint, the full test suite, the release build, Developer ID signing, notarization, stapling, Sparkle Ed25519 signing, ZIP and dSYM packaging, the drag-to-install DMG (built with
dmgbuildfromscript/requirements-dmg.txtin.build/dmgbuild-venv, then signed, notarized and stapled), the CycloneDX SBOM, the manifest, and checksums. It then unzips into a temporary directory and checks layout, resources, licenses, architecture, dSYM UUID, code signature, Gatekeeper, an inert fixture launch, and the DMG contents, checksum and notarization. Outputs inoutputs/:Lerro-macOS-arm64.zip Lerro-macOS-arm64.dmg Lerro-macOS-arm64.dSYM.zip Lerro-macOS-arm64.cdx.json Lerro-release-manifest.json SHA256SUMS.txt -
Deploy the website so the changelog is live before the appcast:
(cd site && npm run deploy) -
Publish the archive and update feed. The website "latest" download serves the DMG; Sparkle updates keep using the ZIP:
./script/publish_cloudflare_release.sh
The script re-verifies the ZIP against the manifest, uploads it to an immutable R2 key, reads it back and compares SHA-256, advances the D1 stable channel head in one batch with a generation check, and fetches the public appcast and download URLs to confirm version, length, and signature.
-
Push, tag, and create the GitHub release:
git push git tag -a vX.Y.Z -m "Lerro X.Y.Z" git push origin vX.Y.Z gh release create vX.Y.Z --title "Lerro X.Y.Z" --notes-file <notes> \ outputs/Lerro-macOS-arm64.zip outputs/Lerro-macOS-arm64.dmg \ outputs/Lerro-macOS-arm64.dSYM.zip \ outputs/Lerro-macOS-arm64.cdx.json outputs/Lerro-release-manifest.json \ outputs/SHA256SUMS.txt
If any step fails, the previous published archive and stable channel head stay in place. Fix the cause, then rerun from a clean tree. Withdrawing a version means moving the D1 stable head back to an earlier published record. Immutable ZIPs stay in R2.
distribution/wrangler.toml holds private Cloudflare identifiers. It is
git-ignored; copy
distribution/wrangler.toml.example on a
new machine. Design and failure policy are in
ADR 0007.
site/ is an Astro static site served by a Cloudflare Worker (lerro-site).
Chinese pages are at /, English at /en. More detail is in
site/README.md.
cd site
npm ci
npm run dev # local server
npm run lint # astro check
npm run build # static build into dist/
npm test # reads dist/, build first
npm run deploy # build, then wrangler deployThe update Worker in distribution/ has its own checks: npm run check && npm test
there.
.github/workflows/ci.yml runs one Linux job: shell
syntax, script/validate_agent_workspace.sh (agent entry points, local links in every
Markdown file, ADR status and sections), the three Python script tests, and the website lint, build, and tests.
Swift build, tests, signing, and packaging run locally in verify_release.sh.
The window never appears or resources are missing. The app was launched from
.build/ directly. Use ./script/build_and_run.sh.
Release build fails on a missing resource bundle or dSYM UUID mismatch. Rebuild
with ./script/build_and_run.sh --release --no-launch. The script lists bundle
inventory differences and compares binary and dSYM UUIDs.
package_release.sh exits with 75. The source tree changed during the build.
Check git status --short, wait for other writers (editors, formatters, other
agents) to finish, and rerun.
Permission is granted in System Settings but Lerro reports it missing. The app
path or signing identity changed, so macOS holds a stale entry. Quit Lerro, remove
the Lerro entry under Privacy & Security > Accessibility, launch the current
build from a stable path (for example /Applications), and grant it again. Use a
development signed build for repeated testing. A single-service TCC reset is
tccutil reset Accessibility app.lerro.mac (or Microphone). Do not run a
global reset.
Speech reports that language resources are not ready. Lerro prepares the
selected locale at launch, on language change, and before capture. If the same
error repeats without a restart, check SpeechTranscriber.installedLocales. After
mobileassetd restarts, AssetInventory.status can report an installed locale as
.supported and a reinstall then fails with Code=4099, while transcription still
works. The resource check in
AppleSpeechService.swift
treats installedLocales as authoritative.
System audio stays muted after a recording. Every exit path (finish, cancel,
Speech failure, analyzer failure, empty transcript) must call
restoreOutputAudioIfNeeded() in
CoreAudioHardware.swift.
A shortcut does nothing. Accessibility must be granted. Open the shortcut
recorder in Settings or onboarding and press the key; the keycap shows pressed and
released state, which shows whether macOS delivers the event. Built-in Fn is key
code 63 and an external Globe key is 179; some external keyboards send no event for
Fn. If Fn still opens the emoji picker, set System Settings > Keyboard > "Press Fn
key to" to Do Nothing and retest. Logs: ./script/build_and_run.sh --telemetry.
Text is not inserted, and the final text is on the clipboard. Strict delivery stopped because the frontmost application, focused element, value, selection, or secure-input state changed after capture, or Accessibility could not read the target. This is the designed fallback. The HUD recovery card offers Copy again.
AI cleanup fails. Open Settings > AI 整理 and check the key status and the balance. A rejected key shows "这个 Key 用不了"; an empty account shows "DeepSeek 余额用完了". Dictate falls back to the Apple transcript when the call fails, and Translate reports the error.
A JSON data file is corrupt. Back up the specific file. Lerro reports the error
and keeps the original file. Do not delete the Application Support folder.
preferences.json contains the plaintext API key, so lint it with
plutil -lint and avoid printing it.