# Build And Verify

Build a SwiftUI macOS app from the command line, install it, and check light and dark...

- Repository: https://github.com/daveebbelaar/bama (1284 stars)
- Category: Design
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add daveebbelaar/bama --skill build-and-verify -g -a claude-code -y`
Codex: `npx skills add daveebbelaar/bama --skill build-and-verify -g -a codex -y`
Cursor: `npx skills add daveebbelaar/bama --skill build-and-verify -g -a cursor -y`
Gemini CLI: `npx skills add daveebbelaar/bama --skill build-and-verify -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add daveebbelaar/bama`

## Description

Build a SwiftUI macOS app from the command line, install it, and check light and dark window snapshots of every page before calling a change done. Use after any UI code change, when a build fails, or when the user asks to run, screenshot, or check the app.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Build and verify

A change is done when four things are true:

1. `./build.sh` finishes with no errors.
2. You looked at the light and dark snapshots of every page you touched.
3. The snapshots match what the user story or reference screenshot asks for.
4. The grid checks pass (`layout-grid` skill).

App not made from the `new-mac-app` template (Xcode, XcodeGen, a menu bar
utility, Swift 5)? Map the commands below with
[existing-app.md](existing-app.md) first.

Do not report a UI change as done from the code alone. SwiftUI code that
compiles can still render an empty sidebar, clipped text, or unreadable dark
mode.

## 1. Build

```bash
./build.sh            # release build, installs ~/Applications/<AppName>.app
./build.sh --debug    # faster build while iterating
./build.sh --open     # also restarts the app so the user sees the new build
```

Read the errors, fix them, and build again. Fix the first error first: later
errors often come from it. If a new file is "not in scope" right after you
created it, run `swift package clean --scratch-path ~/Library/Developer/<AppName>/build`.

## 2. Snapshot

Run the installed binary directly with a test database and a folder for the
images. The app opens, walks through every sidebar page and every Settings
tab in light and dark mode, saves one PNG per page and mode, and quits.

```bash
tools/snap.sh
# SNAPSHOT /tmp/<AppName>-shots/all-light.png
# ...
# SNAPSHOT done /tmp/<AppName>-shots
```

`tools/snap.sh` deletes the old test store (with its `-wal` and `-shm`
files) and the saved window state first, then runs with sample data
(`APP_SEED=1`). Without that, seed data goes stale, and one crashed run
leaves a "reopen windows?" alert that hangs every later run.

Use `APP_SNAPSHOT_PAGES=today,inbox` to limit the pages. Add `settings` to
include the Settings tabs.

The rest: https://github.com/daveebbelaar/bama/blob/HEAD/skills/ship/build-and-verify/SKILL.md