Mac Dev Toolkit

A local-first developer environment manager: snapshot tools and configs, analyze Homebrew health, and generate setup plans from natural language—with a policy-gated runner and a SwiftUI companion app.

Mac Dev Toolkit helps you:

• Reproduce your Mac dev environment reliably
• Detect Homebrew health issues before they break things
• Bootstrap new setups from natural language — safely

Three modules:

1. Brew Intelligence – Orphan detection, conflicts, disk usage, upgrade risk
2. Env Snapshot & Restore – One-click capture and restore of brew, npm, pip, VSCode, shell
3. AI Setup Recommender – Intent → structured install plan (dry-run or execute with confirmation)

---

Architecture

The SwiftUI app is a thin UI layer over the CLI, which wraps a shared Go core.

flowchart TB
    subgraph UI["SwiftUI App (macOS)"]
        A["Snapshot / Brew / AI Setup tabs"]
    end

    subgraph CLI["macdevkit CLI (Cobra)"]
        B["snapshot | brew | ai | doctor"]
    end

    subgraph CORE["Go core"]
        C["brew (parser, analyzer)"]
        D["snapshot (collectors, restore)"]
        E["ai (recommender, plan runner)"]
        F["storage (SQLite)"]
    end

    A -->|"spawns, parses JSON"| B
    B --> C
    B --> D
    B --> E
    B --> F

Loading

Design goals:

• Local-first – no required cloud services; all state lives on your machine.
• CLI as source of truth – the SwiftUI app is an optional UI layer over the same CLI.
• Safe-by-default execution – allowlisted commands only, no sudo, explicit confirmation.
• Idempotent restore – prefer additive, non-destructive restore over “make it look exactly like snapshot”.

---

Quick Start

CLI

go build -o macdevkit ./cli

# Snapshot
./macdevkit snapshot create --name "my-mac"
./macdevkit snapshot list
./macdevkit snapshot delete <id>
./macdevkit snapshot restore --file snapshot.json
./macdevkit snapshot diff --a current --b snapshot.json

# Brew
./macdevkit brew status
./macdevkit brew orphans
./macdevkit brew conflicts
./macdevkit brew plan-upgrade

# AI
./macdevkit ai recommend "build Go web service with Postgres and vector search"
./macdevkit ai run-plan --file plan.json --confirm

SwiftUI App

1. Open app/MacDevKit.xcodeproj in Xcode.
2. Scheme env: Run → Arguments → Environment Variables:
   • MACDEVKIT_PROJECT_DIR = project root (e.g. /Users/you/Documents/Tech/mac-dev-kit).
3. Build (⌘B) — Run Script builds the CLI and copies it into the app bundle.
4. Run (⌘R).

Tabs: Snapshot (Create / List with JSON preview + Delete / Restore), Brew (cached status, scrollable orphans), AI Setup (Generate Plan → Save / Run with dry-run or confirm).

Optional: MACDEVKIT_CLI = path to CLI if not using the embedded binary.

Doctor (diagnostics)

./macdevkit doctor          # human-readable
./macdevkit doctor --json   # for scripting / App

Checks: brew (in PATH and runnable), database (writable, openable), .env (optional). Exit 0 if all ok, 1 otherwise. In the app: Snapshot tab → List → Diagnostics.

---

Safety Model (AI plan execution)

• Allowlist of permitted operations: Only defined step types are run (brew install, brew install --cask, code --install-extension, npm install, etc.). No arbitrary shell or curl | sh.
• No sudo. Commands run with the current user; no elevation.
• No destructive filesystem operations. No rm -rf, no overwriting system dirs.
• Manual confirmation required. Non–dry-run execution requires an explicit flag (--confirm or the app “Run Plan (execute)”); default is dry-run.

---

Plan JSON (AI module)

Plans are structured JSON, not free-form script. Example:

{
  "id": "abc-123",
  "intent": "Go web service with Postgres and vector search",
  "generated_at": "2026-03-01T12:00:00Z",
  "steps": [
    { "type": "brew_install", "package": "postgresql@16", "action": "install", "reason": "Postgres for DB" },
    { "type": "brew_install", "package": "go", "action": "install", "reason": "Go runtime" },
    { "type": "vscode_extension", "package": "golang.go", "action": "install", "reason": "Go extension" }
  ],
  "verification": ["Run 'brew services start postgresql@16' after install"]
}

Allowed step types: brew_install, cask_install, npm_install, vscode_extension (and optionally config_edit, docker_pull depending on implementation). The runner executes only these; anything else is ignored or rejected.

---

Snapshot & Restore

• Snapshot captures brew formulae/casks/taps, npm, pip, VSCode extensions, and optional shell config. Stored in SQLite and/or exported as JSON.
• Restore is plan-based: it computes a diff (what’s missing) and runs installs. Existing packages are not removed; only missing items are installed. No automatic uninstall unless you explicitly use a separate prune flow. Use snapshot diff to compare before restoring.

---

Non-Goals

Mac Dev Toolkit is intentionally scoped. It is not:

• A full system image / bare-metal backup tool (no OS-level images or full-disk snapshots).
• A dotfile sync manager (it doesn’t own your dotfiles; it can coexist with them).
• A package manager replacement (it builds on Homebrew / npm / pip / VSCode, it doesn’t reimplement them).

---

Project Structure

mac-dev-kit/
├── core/           # Go engine (brew, snapshot, ai, storage)
├── cli/            # macdevkit CLI
├── app/            # SwiftUI macOS app (MacDevKit.xcodeproj)
├── macdevkit       # Built CLI binary (gitignored)
├── macdevkit.db    # SQLite (gitignored)
└── README.md

---

Database

macdevkit.db is created on first use (snapshot create or snapshot list) in the current working directory. Override with MACDEVKIT_DB.

• CLI: Run from project root so the DB lives in the project folder.
• App: Uses MACDEVKIT_PROJECT_DIR (or fallback) as CLI working directory so it sees your .env and macdevkit.db.

---

AI Recommender

Uses OpenRouter when configured. No API key = rule-based fallback.

1. Get a key at openrouter.ai/keys.
2. In project root: cp .env.example .env and set OPENROUTER_API_KEY=sk-or-v1-....
3. CLI/app load .env when their working directory is the project (see above).