feat: complete uninstall — stop stranding runner workspaces on disk

Casks/mac-runner.rb

@@ -13,8 +13,23 @@
   binary "#{appdir}/MacRunner.app/Contents/MacOS/MacRunner", target: "mac-runner"
 
   zap trash: [
+    # Runner workspaces live outside Application Support because the GitHub runner
+    # scripts break on paths containing spaces. This is by far the largest artifact:
+    # each configured runner holds an extracted runner release plus its _work checkout.
+    "~/.mac-runner",
     "~/Library/Application Support/MacRunner",
+    "~/Library/Application Support/CrashReporter/MacRunner_*.plist",
+    "~/Library/Application Support/CrashReporter/mac-runner_*.plist",
+    "~/Library/Logs/DiagnosticReports/MacRunner-*.ips",
+    "~/Library/Logs/DiagnosticReports/mac-runner-*.ips",
+    "~/Library/Caches/com.omniaura.mac-runner",
+    "~/Library/HTTPStorages/com.omniaura.mac-runner",
+    "~/Library/HTTPStorages/com.omniaura.mac-runner.binarycookies",
+    "~/Library/HTTPStorages/mac-runner",
+    "~/Library/HTTPStorages/MacRunner",
     "~/Library/Preferences/com.omniaura.mac-runner.plist",
+    "~/Library/Preferences/mac-runner.plist",
+    "~/Library/Saved Application State/com.omniaura.mac-runner.savedState",
   ]
 
   caveats <<~EOS

Makefile

@@ -56,7 +56,16 @@ uninstall:
 	@echo "Uninstalling Mac Runner..."
 	@rm -rf /Applications/MacRunner.app
 	@rm -rf ~/Library/Application\ Support/MacRunner
+	@rm -rf ~/.mac-runner
+	@rm -rf ~/Library/Caches/com.omniaura.mac-runner
+	@rm -rf ~/Library/HTTPStorages/com.omniaura.mac-runner ~/Library/HTTPStorages/mac-runner ~/Library/HTTPStorages/MacRunner
+	@rm -rf "$$HOME/Library/Saved Application State/com.omniaura.mac-runner.savedState"
+	@rm -f ~/Library/Preferences/com.omniaura.mac-runner.plist ~/Library/Preferences/mac-runner.plist
+	@rm -f ~/Library/Application\ Support/CrashReporter/MacRunner_*.plist ~/Library/Application\ Support/CrashReporter/mac-runner_*.plist
+	@rm -f ~/Library/Logs/DiagnosticReports/MacRunner-*.ips ~/Library/Logs/DiagnosticReports/mac-runner-*.ips
 	@echo "Uninstalled"
+	@echo "Note: this does not deregister runners from GitHub."
+	@echo "Run 'mac-runner uninstall' before 'make uninstall' to deregister them first."
 
 # Run tests
 test:

README.md

@@ -72,7 +72,7 @@ mac-runner list
 mac-runner start my-runner
 mac-runner stop my-runner
 
-# Remove (also deletes from GitHub)
+# Remove (deregisters from GitHub and deletes the runner's workspace)
 mac-runner remove my-runner
 
 # Status summary
@@ -81,6 +81,10 @@ mac-runner status
 # Preview or run cleanup (active runner data is always skipped)
 mac-runner cleanup --dry-run
 mac-runner cleanup
+
+# Remove every runner and every file Mac Runner created
+mac-runner uninstall --dry-run
+mac-runner uninstall
 ```
 
 Runners started via CLI persist in the background — they survive the terminal session. Stop and start them from any terminal or from the GUI.
@@ -93,6 +97,38 @@ In Settings, enable **Clean CI Data When Disk Space Is Low** and choose a minimu
 
 Use `mac-runner cleanup --workspaces-only` to preserve all shared caches.
 
+### Uninstalling
+
+`mac-runner uninstall` tears down a Mac Runner installation completely. It stops running
+runners, deregisters them from GitHub, and deletes every location Mac Runner writes to:
+
+| Location | Contents |
+| --- | --- |
+| `~/.mac-runner` | Runner workspaces — the extracted runner release and its `_work` checkout, typically >1 GB each |
+| `~/Library/Application Support/MacRunner` | `config.json`, PID files, container kernel |
+| `~/Library/Preferences/{com.omniaura.mac-runner,mac-runner}.plist` | App and CLI preferences |
+| `~/Library/HTTPStorages/*`, `~/Library/Caches/*` | Cached update checks |
+| `~/Library/Application Support/CrashReporter`, `~/Library/Logs/DiagnosticReports` | Crash and diagnostic reports |
+
+Deregistering first matters: deleting a runner's credentials without telling GitHub leaves
+it listed as a permanently offline runner in the repository's Actions settings.
+
+```bash
+mac-runner uninstall --dry-run      # show exactly what would be deleted, and how much space
+mac-runner uninstall                # prompts before deleting
+mac-runner uninstall --yes          # skip the prompt
+mac-runner uninstall --include-app  # also delete MacRunner.app and the mac-runner symlink
+mac-runner uninstall --keep-runners # delete local files but leave GitHub registrations
+```
+
+Uninstall also removes **orphaned workspaces** — directories left on disk by earlier
+versions that deleted a runner from `config.json` without deleting its files. If you have
+been using Mac Runner for a while, `--dry-run` is worth running even if you have no runners
+configured.
+
+If you installed with Homebrew, remove the app itself with `brew uninstall --cask mac-runner`.
+Use `brew uninstall --zap --cask mac-runner` to remove the app and all of its data in one step.
+
 ## CI/CD: Self-Hosted Runner with Automatic Cloud Fallback
 
 Mac Runner uses a pattern that automatically routes CI jobs to your self-hosted Mac when it's online, and falls back to GitHub-hosted cloud runners when it's not. This means pushes to main always build, regardless of whether your Mac is on.

Sources/Services/CLIHandler.swift

@@ -97,6 +97,8 @@ enum CLIHandler {
             await handleStatus()
         case "setup":
             await handleSetup(args: Array(args.dropFirst()))
+        case "uninstall":
+            await handleUninstall(args: Array(args.dropFirst()))
         case "cleanup":
             await handleCleanup(args: Array(args.dropFirst()))
         default:
@@ -127,6 +129,7 @@ enum CLIHandler {
           status            Show runner status summary
           setup             Set up dedicated user isolation
           cleanup           Remove idle runner workspaces and CI caches
+          uninstall         Remove all runners and every file Mac Runner created
           help              Show this help message
           version           Show version
 
@@ -145,6 +148,12 @@ enum CLIHandler {
           --dry-run         Show what would be removed
           --workspaces-only Keep shared language, Homebrew, and Xcode caches
 
+        UNINSTALL OPTIONS:
+          --dry-run         Show what would be removed without deleting anything
+          --yes, -y         Skip the confirmation prompt
+          --include-app     Also delete MacRunner.app and the mac-runner symlink
+          --keep-runners    Leave runners registered on GitHub (delete local files only)
+
         EXAMPLES:
           mac-runner auth
           mac-runner add owner/repo --name my-runner --labels macos,arm64
@@ -430,6 +439,176 @@ enum CLIHandler {
         }
     }
 
+    @MainActor
+    private static func handleUninstall(args: [String]) async {
+        let dryRun = args.contains("--dry-run")
+        let assumeYes = args.contains("--yes") || args.contains("-y")
+        let includeApplication = args.contains("--include-app")
+        let keepRunners = args.contains("--keep-runners")
+
+        let config: RunnerConfig
+        do {
+            config = try ConfigService().loadConfig()
+        } catch {
+            print("Error: failed to load config: \(error.localizedDescription)")
+            return
+        }
+
+        let service = UninstallService()
+        let plan = service.plan(
+            runners: config.runners,
+            globalIsolationMode: config.settings.isolationMode,
+            includeApplication: includeApplication
+        )
+
+        guard !plan.isEmpty else {
+            print("Nothing to uninstall - no Mac Runner files found.")
+            return
+        }
+
+        printPlan(plan, keepRunners: keepRunners)
+
+        if dryRun {
+            let size = ByteCountFormatter.string(fromByteCount: plan.totalBytes, countStyle: .file)
+            print("")
+            print("Dry run: nothing was deleted. \(plan.items.count) item(s), \(size) would be freed.")
+            return
+        }
+
+        if !assumeYes {
+            print("")
+            print("This cannot be undone. Continue? [y/N] ", terminator: "")
+            guard let response = readLine()?.trimmingCharacters(in: .whitespaces).lowercased(),
+                  response == "y" || response == "yes" else {
+                print("Uninstall cancelled.")
+                return
+            }
+        }
+
+        // Stop anything still running so its workspace is not deleted mid-job.
+        //
+        // RunnerManager is built only when there is something to stop: constructing it
+        // pulls in UNUserNotificationCenter, which traps when the CLI runs outside an app
+        // bundle - the exact state a user is in when uninstalling after deleting the app.
+        let runningRunners = config.runners.filter { $0.status == .running }
+        if !runningRunners.isEmpty {
+            let manager = RunnerManager()
+            for runner in runningRunners {
+                print("Stopping '\(runner.name)'...")
+                try? await manager.stopRunner(runner.id)
+            }
+        }
+
+        // Deregister from GitHub before the credentials are deleted, otherwise the
+        // runners linger in repository settings as permanently offline entries.
+        var deregistered: [String] = []
+        var failedDeregistrations: [String] = []
+        if !keepRunners {
+            for runner in plan.runnersToDeregister {
+                guard let ghId = runner.githubRunnerId else { continue }
+                do {
+                    try await GHCLIService.shared.deleteRunner(target: runner.target, githubRunnerId: ghId)
+                    deregistered.append(runner.name)
+                } catch {
+                    failedDeregistrations.append("\(runner.name) (\(runner.repo))")
+                }
+            }
+        }
+
+        let report = service.execute(
+            plan: plan,
+            dryRun: false,
+            deregistered: deregistered,
+            failedDeregistrations: failedDeregistrations
+        )
+
+        printReport(report, service: service, includedApplication: includeApplication, keepRunners: keepRunners)
+    }
+
+    private static func printPlan(_ plan: UninstallPlan, keepRunners: Bool) {
+        print("Mac Runner uninstall")
+        print("")
+
+        if !plan.activeRunnerNames.isEmpty {
+            print("Running runners (will be stopped): \(plan.activeRunnerNames.joined(separator: ", "))")
+            print("")
+        }
+
+        if !keepRunners && !plan.runnersToDeregister.isEmpty {
+            print("Will deregister from GitHub:")
+            for runner in plan.runnersToDeregister {
+                print("  \(runner.name)  (\(runner.repo))")
+            }
+            print("")
+        }
+
+        print("Will delete:")
+        let pathWidth = min(plan.items.map(\.path.count).max() ?? 0, 72)
+        for item in plan.items {
+            let size = ByteCountFormatter.string(fromByteCount: item.bytes, countStyle: .file)
+            let path = abbreviate(item.path)
+            let padded = path.padding(toLength: max(pathWidth, path.count), withPad: " ", startingAt: 0)
+            print("  \(padded)  \(size.padding(toLength: 10, withPad: " ", startingAt: 0))  \(item.category.rawValue)")
+        }
+
+        let total = ByteCountFormatter.string(fromByteCount: plan.totalBytes, countStyle: .file)
+        print("")
+        print("Total: \(plan.items.count) item(s), \(total)")
+    }
+
+    private static func printReport(
+        _ report: UninstallReport,
+        service: UninstallService,
+        includedApplication: Bool,
+        keepRunners: Bool
+    ) {
+        let size = ByteCountFormatter.string(fromByteCount: report.reclaimedBytes, countStyle: .file)
+        print("")
+        print("Removed \(report.removedPaths.count) item(s), freed \(size).")
+
+        if !report.deregisteredRunners.isEmpty {
+            print("Deregistered from GitHub: \(report.deregisteredRunners.joined(separator: ", "))")
+        }
+
+        if !report.failedDeregistrations.isEmpty {
+            print("")
+            print("Could not deregister: \(report.failedDeregistrations.joined(separator: ", "))")
+            print("These remain listed as offline runners. Remove them from the repository's")
+            print("Settings > Actions > Runners page.")
+        }
+
+        if !report.failedPaths.isEmpty {
+            print("")
+            print("Could not remove:")
+            for path in report.failedPaths {
+                print("  \(abbreviate(path))")
+            }
+        }
+
+        if keepRunners {
+            print("")
+            print("Runners were left registered on GitHub (--keep-runners).")
+        }
+
+        if !includedApplication {
+            print("")
+            if service.isHomebrewManaged() {
+                print("Local data is gone. To remove the app itself, run:")
+                print("  brew uninstall --cask mac-runner")
+            } else {
+                print("Local data is gone. To remove the app itself, re-run with --include-app")
+                print("or delete /Applications/MacRunner.app manually.")
+            }
+        }
+    }
+
+    /// Render a home-relative path as `~/...` so plan output stays readable.
+    private static func abbreviate(_ path: String) -> String {
+        let home = FileManager.default.homeDirectoryForCurrentUser.path
+        guard path.hasPrefix(home) else { return path }
+        return "~" + path.dropFirst(home.count)
+    }
+
     private static func handleCleanup(args: [String]) async {
         let dryRun = args.contains("--dry-run")
         let includeSharedCaches = !args.contains("--workspaces-only")