Developing Stow

Building, testing and reviewing Stow from source. How the app works inside is in
ARCHITECTURE.md; what is left to build is in ROADMAP.md.

Requirements

• macOS 26 or later (uses Liquid Glass APIs directly — no fallbacks)
• Xcode 27, XcodeGen (brew install xcodegen)

Build & run

scripts/fetch-7zip.sh   # pinned 7-Zip 26.04, checksum-verified, into Vendor/ (gitignored)
xcodegen generate
xcodebuild -project Stow.xcodeproj -scheme Stow -derivedDataPath build build
open build/Build/Products/Debug/Stow.app

Tests (Swift Testing): xcodebuild -project Stow.xcodeproj -scheme Stow -derivedDataPath build test

Encrypted/split/verified packing stress (#38): after the setup above, run
scripts/stress-encrypted-split.sh [rounds] (default 20, maximum 100). Each round creates through
the sandboxed engine, verifies, reopens and extracts the numbered 7Z parts, checks wrong-password
refusal and payload/source integrity, and rejects failed, skipped or missing tests. Logs and
result bundles are retained in the printed build/packing-stress.* directory.

After each build, scripts/register-extensions.sh registers that build's Quick Look and Finder
extensions (ad-hoc signatures change every build, and several worktrees may hold a Stow.app).

Stow.xcodeproj is generated — edit project.yml, not the project.

Design review screenshots

scripts/snapshot.sh <scene> [light|dark]   # → snapshots/

Scenes: editing, readonly, welcome, grid, list, fonts, search, search-open, activity, pack, draft-empty, draft, draft-save (the new-archive draft and its Save sheet), tray, quicklook
(-StowPreview encrypted|slow), associations, integration (-StowRepair YES), batch,
conflict, conflict-folder, signature-warning, replace-app, extract-options, install-options,
packing, packed, packrun, checkup, install-preparing, install-done, open-unreadable, Details and archive notices (details-clean, details-planned,
details-more, details-notices-open, details-folder, details-multi, details-edited, details-app,
details-app-signed, details-long; -StowNoticesOpen YES opens the notice card in any scene, -StowArchiveInfoOpen YES the title menu's Archive Info popover), source-access, source-access-file (both take -StowSourcePath <file> or
-StowSourceName <name>), source-access-unsaved, browser-opening and glance-opening (an archive still opening). Browsing scenes take -StowOpen <path>
(-StowOpenPreferred YES routes it as Finder does, into the window Settings › Glance picks) plus the flags listed in
App/Browser/BrowseDemo.swift.
open -StowOpen <path> -StowRun extractAll|install|fonts|installer runs a real step
(-StowInstallFolder/-StowExtractFolder point it at scratch folders); with a locked screen,
-StowSnapshotMode view draws the view tree instead of the composited window.
Display preferences can't be turned on by a launch argument, so any scene takes debug-only overrides:
-StowReduceTransparency YES (Stow's solid fallbacks for glass), -StowIncreaseContrast YES (Stow's
own borders and colours) and -StowReduceMotion YES (Stow's fades in place of movement). None reaches
system controls, the accent's high-contrast variant or AppKit's own window animations: an app can't take
the system's settings itself, so the real switches still need a pass by hand.

Motion is reviewed in frame bursts: -StowBurst <transition> plays one transition, by click and as after a
key press, and writes a contact sheet of frames at fixed offsets (App/DemoBurst.swift lists the
transitions; -StowBurstCrop x,y,w,h crops, in points). scripts/motion-bursts.sh <dir> [transition…]
captures each one light and dark, plain and with each override.

Test fixtures are rebuilt with scripts/make-fixtures.sh (disk images) and
scripts/make-browse-fixtures.sh [--big] (browsing, 100k entries).
Use scripts/make-fixtures.sh --compatibility-only for the self-generated realistic installer:
8 KiB Finder store leaves, a multi-resolution root TIFF, a regular Applications bookmark and a
named ICNS companion. The private real-image corpus runner and coverage are described in
the DMG compatibility report.

Settings keys

Settings keys (UserDefaults; the resettable list and defaults are in SettingsKeys):

Layout