Feat/macos swiftui dashboard

.gitignore

@@ -12,6 +12,11 @@ node_modules/
 web/dist/
 internal/server/dist/*
 
+# SwiftPM
+macos/**/.build/
+macos/**/.swiftpm/
+/macos/build/
+
 # Dev-only UI prototypes (not shipped). See web/src/App.tsx SampleRoutes.
 web/src/sample/
 

HANDOFF.md

@@ -3,6 +3,15 @@
 Last updated: 2026-08-08. Branch: `main`. Working tree: clean.
 **11 commits are committed locally but NOT pushed** (`dff21d7`..`0119b7a`).
 
+## Current state (2026-09-18)
+
+macOS has an optional native SwiftUI dashboard in `macos/` (`make macos`):
+`AntaresKit` plus the `Antares` SwiftUI app, talking HTTP/SSE to `:8787`.
+The Mac app is optional; the CLI `antares` still serves the embedded React
+dashboard for Linux, Windows, and anyone who does not build the app. The Go
+backend was not rewritten. Session log below is from 2026-08-08 and is
+otherwise unchanged.
+
 ## Goal
 
 Ongoing maintenance of Antares (Go backend + React/Vite dashboard in `web/`).

Makefile

@@ -7,6 +7,7 @@ tool = $(shell command -v $(1) 2>/dev/null || echo $(2))
 
 GO     ?= $(call tool,go,$(HOME)/.local/sdk/go/bin/go)
 BUN    ?= $(call tool,bun,$(HOME)/.bun/bin/bun)
+SWIFT  ?= $(call tool,swift,/usr/bin/swift)
 # air lives in GOPATH/bin after `make install`; if GOPATH can't be read, use the
 # conventional ~/go.
 GOPATH ?= $(shell $(GO) env GOPATH 2>/dev/null || echo $(HOME)/go)
@@ -20,6 +21,9 @@ LDFLAGS := -s -w \
   -X github.com/enowdev/antares/internal/version.Version=$(VERSION) \
   -X github.com/enowdev/antares/internal/version.Commit=$(COMMIT) \
   -X github.com/enowdev/antares/internal/version.Date=$(DATE)
+MACOS_APP := macos/build/Build/Products/Release/Antares.app
+MACOS_APP_CONTENTS := $(MACOS_APP)/Contents
+MACOS_APP_MACOS := $(MACOS_APP_CONTENTS)/MacOS
 
 .PHONY: help
 help: ## Show this help
@@ -81,6 +85,18 @@ build-fixture: ## Build the smoke-only fixture helper (cmd/smokefixture)
 build-api: ## Build the backend only (no dashboard)
 	@$(GO) build -trimpath -ldflags "$(LDFLAGS)" -o bin/antares ./cmd/antares
 
+.PHONY: macos
+macos: build ## Build Antares.app with the darwin antares binary inside
+	@test "$$(uname -s)" = Darwin || (echo "macos target requires Darwin" && exit 1)
+	@$(SWIFT) build -c release --package-path macos/Antares
+	@rm -rf "$(MACOS_APP)"
+	@mkdir -p "$(MACOS_APP_MACOS)"
+	@cp macos/Antares/.build/release/Antares "$(MACOS_APP_MACOS)/AntaresApp"
+	@cp bin/antares "$(MACOS_APP_MACOS)/antares"
+	@cp macos/Antares/Info.plist "$(MACOS_APP_CONTENTS)/Info.plist"
+	@chmod +x "$(MACOS_APP_MACOS)/AntaresApp" "$(MACOS_APP_MACOS)/antares"
+	@echo "built $(MACOS_APP)"
+
 .PHONY: install-cli
 install-cli: build ## Build (with dashboard) and install `antares` to $(PREFIX)/bin
 	@mkdir -p $(PREFIX)/bin
@@ -139,6 +155,7 @@ release: ## Cross-compile release binaries for all platforms into dist/release
 
 .PHONY: clean
 clean: ## Remove build artefacts
+	@rm -rf bin .air web/dist dist macos/build
 	@rm -rf bin .air web/dist dist desktop/bin
 	@echo "cleaned"
 

README.md

@@ -67,6 +67,10 @@ antares setup        # configure it, in the browser or the terminal
 
 Runs on **Linux**, **macOS**, and **Windows**.
 
+Mac operators can also build an optional native dashboard companion with `make macos`.
+The Mac app is optional; the CLI `antares` still serves the web UI for other
+platforms.
+
 ---
 
 ## A look at it

docs/architecture.md

@@ -23,6 +23,7 @@ internal/
   wsutil/             a minimal RFC 6455 client
   config/             layered configuration and its schema
 web/                  the React dashboard
+macos/                AntaresKit + Antares SwiftUI companion (HTTP/SSE to :8787)
 ```
 
 ## The turn
@@ -81,6 +82,8 @@ everywhere and adding one is a single registration.
 
 **The dashboard embedded.** `make build` copies `web/dist` into the binary. One
 file to copy anywhere. In development Vite serves the UI and proxies the API.
+On macOS, `make macos` can also build an optional native SwiftUI companion; it
+does not replace the Go process or the embedded web dashboard.
 
 ## The dashboard
 
@@ -92,6 +95,12 @@ load only when selected. Development sample routes are excluded from production.
 Built with React 19, Vite, Tailwind v4 with oklch tokens, Radix primitives, and
 Phosphor icons. Five languages, English by default.
 
+macOS has an optional native companion in `macos/`: `AntaresKit` (HTTP, SSE,
+process supervisor) plus the `Antares` SwiftUI app. It talks only to the
+existing Go API at `http://127.0.0.1:8787`. The Mac app is optional; the CLI
+`antares` still serves the web UI for other platforms. The Go backend is
+unchanged.
+
 ## Streaming
 
 Events flow the same way to every surface:

docs/getting-started.md

@@ -25,6 +25,21 @@ make build       # one binary with the dashboard inside it
 ./bin/antares
 ```
 
+## macOS app
+
+The Mac app is optional. Building it requires Xcode or the Swift toolchain.
+The CLI `antares` and `antares tui` are unchanged: they still start the Go
+backend and serve the embedded web dashboard on every platform, including
+Linux and Windows.
+
+```bash
+make macos
+open macos/build/Build/Products/Release/Antares.app
+```
+
+The app starts `antares --foreground` if nothing is listening on :8787.
+Linux and Windows still use the web dashboard.
+
 The first run has nothing configured, so it drops straight into setup:
 
 ```