kurtschwarz/herder

A monorepo. Today it holds one macOS app; more apps and services go beside it.
## Layout
herder/
├── justfile # forwards every task to an app or service
├── apps/
│ └── herder/ # the macOS app
│ ├── AGENTS.md # where a new file goes; points at docs/ARCHITECTURE.md
│ ├── docs/
│ │ └── ARCHITECTURE.md # the rulebook: layers, state, concurrency
│ ├── justfile # how to build, test and run this app
│ ├── project.yml # source of truth for Herder.xcodeproj
│ ├── scripts/ # check-boundaries.sh, the import rules a compiler can't see
│ ├── Herder/ # thin app target: entry point and resources only
│ ├── HerderKit/ # all the code, split into modules
│ └── UITests/ # XCTest, since Swift Testing has no UI automation
└── packages/
└── herder-syntax-highlighter/ # Rust: tree-sitter grammars behind a C ABI
New apps go in apps/ /. Services go in services/ /. A package under
packages/ is for code that does not belong inside one app: either because more
than one of them uses it, or because it is not written in the app's language.
packages/herder-syntax-highlighter is the second kind — Rust, consumed by the macOS app as an
XCFramework.
apps/herder/docs/ARCHITECTURE.md is the rulebook for the app, and it wins
over this file. What is here is the monorepo and a tour; what is there is the
layering, the dependency rules, the state model and the conventions, in enough
detail to settle an argument.
## Getting started
sh
just bootstrap apps/herder # builds the syntax crate, generates Herder.xcodeproj
just test apps/herder # fast module tests, no app host
just dev apps/herder # build and run, logs in the terminal
Requires Xcode 26+, brew install just xcodegen, and a Rust toolchain
(brew install rustup && rustup-init). just bootstrap installs the Rust
targets it needs.
HerderKit has a .binaryTarget pointing at an XCFramework built from
packages/herder-syntax-highlighter, so a fresh clone must run just bootstrap apps/herder before
the Swift package will resolve. Every recipe that compiles Swift rebuilds the
crate first: a stale static library would link without complaint and highlight
with yesterday's grammars.
## Commands
Every recipe takes the path to an app or service, so the same verbs work across the
repo as it grows:
| Command | Does |
| just build | Build it |
| just test | Run its tests. Extra arguments pass through: just test apps/herder -only-testing:CoreTests |
| just dev | Build and run it, with its output in your terminal |
| just bootstrap | Set it up in a fresh clone |
| just clean | Remove its build artifacts |
| just in | Run anything else it defines, e.g. just in apps/herder uitest |
| just test-all | Test every app and service |
| just list | List the apps and services |
The root justfile only forwards. Each app or service owns a justfile with those
recipe names, which is what lets a Swift app and, later, a Go service sit side by
side without the root knowing anything about either toolchain. just on its own
lists every recipe, in either place.
Stopping just dev with either Ctrl-C or Cmd-Q exits 0 and prints nothing extra.
That takes a signal trap at each layer: Ctrl-C goes to every process in the
terminal's foreground group, so without one, the recipe's own shell dies by signal