Harden lifecycle and refresh onboarding

Author: djadmin

.github/workflows/cli.yml

@@ -0,0 +1,27 @@
+name: CLI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  cli-tests:
+    runs-on: macos-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Ensure jq is installed
+        run: |
+          command -v jq >/dev/null 2>&1 || brew install jq
+
+      - name: Syntax check CLI and tests
+        run: |
+          bash -n bin/devkit
+          bash -n test/test_registry.sh
+          bash -n devkit_test/test_registry.sh
+
+      - name: Run CLI integration suite
+        run: bash test/test_registry.sh

.github/workflows/installer.yml

@@ -0,0 +1,24 @@
+name: Installer
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  installer-smoke:
+    runs-on: macos-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Ensure jq is installed
+        run: |
+          command -v jq >/dev/null 2>&1 || brew install jq
+
+      - name: Syntax check installer smoke test
+        run: bash -n test/test_install.sh
+
+      - name: Run installer smoke test
+        run: bash test/test_install.sh

CLAUDE.md

@@ -12,7 +12,7 @@ Core primitives:
 
 - a registry of local apps (`apps.json`, gitignored)
 - stable localhost hostnames via Caddy
-- `pm2` lifecycle helpers
+- native PID-file lifecycle helpers
 - a generated dashboard at `http://dash.localhost`
 - `devkit edit <name>` → drops into project with Claude Code running
 

MenuBarApp/CHANGELOG.md

@@ -26,7 +26,7 @@ All notable changes to devkit are documented here.
 
 **Known issues (beta)**
 
-- Stop may not kill externally-supervised processes (pm2, nodemon, launchd-managed)
+- Externally-supervised processes (nodemon, launchd, custom respawners) can come back after stop
 - Auto-update not yet implemented
 - Launch at login not yet implemented
 - Homebrew cask not yet published

MenuBarApp/DevkitBar/DevkitBar.entitlements

@@ -2,7 +2,7 @@
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
-    <!-- Sandbox off: we need to spawn devkit/pm2 processes and read arbitrary paths -->
+    <!-- Sandbox off: we need to spawn devkit-managed processes and read arbitrary paths -->
     <key>com.apple.security.app-sandbox</key>
     <false/>
     <key>com.apple.security.network.client</key>

MenuBarApp/DevkitBar/Services/AppRegistry.swift

@@ -141,11 +141,17 @@ final class AppRegistry: ObservableObject {
         guard !pendingOps.contains(app.id) else { return }
         pendingOps.insert(app.id)
         statuses[app.id] = .checking
+        errorMessage = nil
 
         Task {
             defer { pendingOps.remove(app.id) }
 
-            await DevkitCLI.start(app.name)
+            let result = await DevkitCLI.start(app.name)
+            guard result.exitCode == 0 else {
+                statuses[app.id] = .stopped
+                errorMessage = result.output.trimmingCharacters(in: .whitespacesAndNewlines)
+                return
+            }
 
             // Poll until the port responds (up to 6s)
             for _ in 0..<10 {
@@ -163,57 +169,34 @@ final class AppRegistry: ObservableObject {
         guard !pendingOps.contains(app.id) else { return }
         pendingOps.insert(app.id)
         statuses[app.id] = .checking
+        errorMessage = nil
 
         Task {
             defer { pendingOps.remove(app.id) }
 
-            // 1. Tell devkit to stop it (updates its own process table)
-            await DevkitCLI.stop(app.name)
-
-            // 2. Kill by port — targets the LISTENING process only (-sTCP:LISTEN),
-            //    works regardless of what devkit's stop command does.
-            //    SIGTERM first, then SIGKILL 500ms later if still alive.
-            await killListeningProcess(on: app.port)
+            let result = await DevkitCLI.stop(app.name)
+            guard result.exitCode == 0 else {
+                let stillUp = await PortChecker.isReachable(port: app.port)
+                statuses[app.id] = stillUp ? .running : .stopped
+                errorMessage = result.output.trimmingCharacters(in: .whitespacesAndNewlines)
+                return
+            }
 
-            // 3. Verify: poll until port is actually closed (up to 4s)
-            for _ in 0..<8 {
+            // Verify: poll until port is actually closed (up to 6s)
+            for _ in 0..<12 {
                 try? await Task.sleep(for: .milliseconds(500))
                 if !(await PortChecker.isReachable(port: app.port)) {
                     statuses[app.id] = .stopped
                     return
                 }
             }
 
-            // Port is still open after 4s — let polling decide the real status
-            // (process might be managed externally and respawned)
+            // Port is still open after 6s — let polling decide the real status.
             let stillUp = await PortChecker.isReachable(port: app.port)
             statuses[app.id] = stillUp ? .running : .stopped
         }
     }
 
-    // MARK: – Port kill
-
-    /// Kills the process listening on the given TCP port.
-    /// Uses `-sTCP:LISTEN` so only the server process is targeted, not clients connected to it.
-    private func killListeningProcess(on port: Int) async {
-        await withCheckedContinuation { (cont: CheckedContinuation<Void, Never>) in
-            let task = Process()
-            task.executableURL = URL(fileURLWithPath: "/bin/sh")
-            task.arguments = ["-c", """
-                pids=$(lsof -nP -iTCP:\(port) -sTCP:LISTEN -t 2>/dev/null)
-                if [ -n "$pids" ]; then
-                    echo "$pids" | xargs kill -TERM 2>/dev/null
-                    sleep 0.5
-                    pids=$(lsof -nP -iTCP:\(port) -sTCP:LISTEN -t 2>/dev/null)
-                    [ -n "$pids" ] && echo "$pids" | xargs kill -KILL 2>/dev/null
-                fi
-            """]
-            task.terminationHandler = { _ in cont.resume() }
-            do    { try task.run() }
-            catch { cont.resume() }
-        }
-    }
-
     // MARK: – Derived
 
     func status(for app: AppEntry) -> AppStatus { statuses[app.id] ?? .checking }

MenuBarApp/DevkitBar/Services/DevkitCLI.swift

@@ -1,6 +1,11 @@
 import Foundation
 
 enum DevkitCLI {
+    struct Result {
+        let output: String
+        let exitCode: Int32
+    }
+
     // Resolved once at startup. Checks known locations first, then falls back
     // to asking the shell (sources ~/.zshrc so custom PATH installs are found).
     static let binaryPath: String? = {
@@ -29,12 +34,14 @@ enum DevkitCLI {
     }()
 
     @discardableResult
-    static func run(_ subcommand: String) async -> String {
-        guard let binary = binaryPath else { return "" }
+    static func run(_ args: [String]) async -> Result {
+        guard let binary = binaryPath else {
+            return Result(output: "devkit not found — install the CLI first", exitCode: 127)
+        }
         return await withCheckedContinuation { cont in
             let task = Process()
             task.executableURL = URL(fileURLWithPath: "/bin/zsh")
-            task.arguments = ["-l", "-c", "source ~/.zshrc 2>/dev/null; \(binary) \(subcommand)"]
+            task.arguments = ["-l", "-c", "source ~/.zshrc 2>/dev/null; exec \"$@\"", "devkit", binary] + args
 
             var env = ProcessInfo.processInfo.environment
             env["PATH"] = "/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
@@ -44,22 +51,25 @@ enum DevkitCLI {
             task.standardOutput = out
             task.standardError  = err
 
-            task.terminationHandler = { _ in
-                let data = out.fileHandleForReading.readDataToEndOfFile()
-                cont.resume(returning: String(data: data, encoding: .utf8) ?? "")
+            task.terminationHandler = { task in
+                let data = out.fileHandleForReading.readDataToEndOfFile() + err.fileHandleForReading.readDataToEndOfFile()
+                cont.resume(returning: Result(
+                    output: String(data: data, encoding: .utf8) ?? "",
+                    exitCode: task.terminationStatus
+                ))
             }
             do    { try task.run() }
-            catch { cont.resume(returning: "") }
+            catch { cont.resume(returning: Result(output: "", exitCode: 1)) }
         }
     }
 
     static func appsJSONPath() async -> String? {
-        let output = await run("paths")
-        return output.split(separator: "\n")
+        let result = await run(["paths"])
+        return result.output.split(separator: "\n")
             .first { $0.hasPrefix("APPS_JSON=") }
             .map { String($0.dropFirst("APPS_JSON=".count)) }
     }
 
-    static func start(_ name: String) async { await run("start \(name)") }
-    static func stop(_ name: String)  async { await run("stop \(name)") }
+    static func start(_ name: String) async -> Result { await run(["start", name]) }
+    static func stop(_ name: String)  async -> Result { await run(["stop", name]) }
 }

MenuBarApp/DevkitBar/Views/AppRowView.swift

@@ -147,8 +147,8 @@ private struct StatusDot: View {
         .onAppear {
             if status == .running { pulse = true }
         }
-        .onChange(of: status) { new in
-            pulse = (new == .running)
+        .onChange(of: status) { _, newValue in
+            pulse = (newValue == .running)
         }
         .animation(.easeInOut(duration: 0.3), value: status)
     }

MenuBarApp/DevkitBar/Views/MenuBarView.swift

@@ -82,7 +82,7 @@ struct MenuBarView: View {
                 .textFieldStyle(.plain)
                 .font(.system(size: 12.5))
                 .focused($searchFocused)
-                .onChange(of: searchText) { v in searchPublisher.send(v) }
+                .onChange(of: searchText) { _, newValue in searchPublisher.send(newValue) }
                 .onExitCommand { searchText = ""; debouncedQuery = ""; searchFocused = false }
 
             if !searchText.isEmpty {