Add Tools -> Install CLI for installing pn into ~/.local/bin

pn install now defaults to ~/.local/bin, relinks stale symlinks that
point at other executables, and appends a ~/.zprofile PATH entry when
the login zsh PATH lacks the install directory. The app menu action
resolves the user's real home via getpwuid and launches the bundled
helper from Contents/Helpers under new sandbox exceptions for ~/.local
and ~/.zprofile.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: livid

Planet/Helper/KeyboardShortcutHelper.swift

@@ -204,6 +204,12 @@ class KeyboardShortcutHelper: ObservableObject {
 
                 apiConsoleMenus()
 
+                Button {
+                    self.installCLIAction()
+                } label: {
+                    Text("Install CLI")
+                }
+
                 Button {
                     AppLogWindowManager.shared.open()
                 } label: {
@@ -329,6 +335,138 @@ class KeyboardShortcutHelper: ObservableObject {
         }
     }
 
+    private func installCLIAction() {
+        if installedCLILinksToBundledCLI {
+            do {
+                try runCLIInstall()
+                presentCLIAlreadyInstalledAlert()
+            }
+            catch {
+                presentCLIInstallError(error)
+            }
+            return
+        }
+
+        let alert = NSAlert()
+        alert.messageText = L10n("Install CLI")
+        alert.informativeText = L10n("Install the pn CLI to ~/.local/bin so it becomes available in Terminal?")
+        alert.alertStyle = .informational
+        alert.addButton(withTitle: L10n("Install"))
+        alert.addButton(withTitle: L10n("Cancel"))
+
+        guard alert.runModal() == .alertFirstButtonReturn else { return }
+
+        do {
+            try runCLIInstall()
+            presentCLIInstalledAlert(
+                messageText: L10n("CLI Installed"),
+                informativeText: L10n("A symbolic link for pn has been installed at ~/.local/bin/pn and can be used in Terminal.")
+            )
+        }
+        catch {
+            presentCLIInstallError(error)
+        }
+    }
+
+    private var installedCLILinksToBundledCLI: Bool {
+        guard let destination = try? FileManager.default.destinationOfSymbolicLink(atPath: cliInstallURL.path) else {
+            return false
+        }
+        let destinationURL = destination.hasPrefix("/")
+            ? URL(fileURLWithPath: destination)
+            : cliInstallURL.deletingLastPathComponent().appendingPathComponent(destination)
+        return destinationURL.standardizedFileURL.resolvingSymlinksInPath().path
+            == bundledCLIURL.resolvingSymlinksInPath().path
+    }
+
+    private var cliInstallDirectory: URL {
+        cliRealHomeDirectory.appendingPathComponent(".local/bin", isDirectory: true)
+    }
+
+    // In the sandbox, homeDirectoryForCurrentUser points to the app container;
+    // the CLI must be installed relative to the user's real home directory.
+    private var cliRealHomeDirectory: URL {
+        if let home = getpwuid(getuid())?.pointee.pw_dir {
+            return URL(fileURLWithPath: String(cString: home), isDirectory: true)
+        }
+        return FileManager.default.homeDirectoryForCurrentUser
+    }
+
+    private var cliInstallURL: URL {
+        cliInstallDirectory.appendingPathComponent("pn", isDirectory: false)
+    }
+
+    // pn is embedded in Contents/Helpers, which url(forAuxiliaryExecutable:)
+    // does not search.
+    private var bundledCLIURL: URL {
+        Bundle.main.bundleURL
+            .appendingPathComponent("Contents/Helpers/pn", isDirectory: false)
+    }
+
+    private func runCLIInstall() throws {
+        let cliURL = bundledCLIURL
+        guard FileManager.default.isExecutableFile(atPath: cliURL.path) else {
+            throw CLIInstallError.helperNotFound
+        }
+
+        let process = Process()
+        let outputPipe = Pipe()
+        process.executableURL = cliURL
+        process.arguments = ["install", "--to", cliInstallDirectory.path]
+        process.standardOutput = outputPipe
+        process.standardError = outputPipe
+
+        try process.run()
+        process.waitUntilExit()
+
+        let outputData = outputPipe.fileHandleForReading.readDataToEndOfFile()
+        let output = String(data: outputData, encoding: .utf8)?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+
+        guard process.terminationStatus == 0 else {
+            throw CLIInstallError.installFailed(output ?? L10n("pn install failed."))
+        }
+    }
+
+    private func presentCLIAlreadyInstalledAlert() {
+        presentCLIInstalledAlert(
+            messageText: L10n("CLI Already Installed"),
+            informativeText: L10n("A symbolic link for pn is already installed at ~/.local/bin/pn and can be used in Terminal.")
+        )
+    }
+
+    private func presentCLIInstallError(_ error: Error) {
+        let alert = NSAlert()
+        alert.messageText = L10n("Failed to Install CLI")
+        alert.informativeText = error.localizedDescription
+        alert.alertStyle = .warning
+        alert.addButton(withTitle: L10n("OK"))
+        alert.runModal()
+    }
+
+    private func presentCLIInstalledAlert(messageText: String, informativeText: String) {
+        let alert = NSAlert()
+        alert.messageText = messageText
+        alert.informativeText = informativeText
+        alert.alertStyle = .informational
+        alert.addButton(withTitle: L10n("OK"))
+        alert.addButton(withTitle: L10n("Open Terminal"))
+
+        if alert.runModal() == .alertSecondButtonReturn {
+            openTerminal()
+        }
+    }
+
+    private func openTerminal() {
+        guard let appURL = NSWorkspace.shared.urlForApplication(withBundleIdentifier: "com.apple.Terminal") else {
+            return
+        }
+
+        let configuration = NSWorkspace.OpenConfiguration()
+        configuration.activates = true
+        NSWorkspace.shared.openApplication(at: appURL, configuration: configuration, completionHandler: nil)
+    }
+
     // MARK: -
 
     private func importArticleAction() {
@@ -507,3 +645,17 @@ class KeyboardShortcutHelper: ObservableObject {
         PlanetAPIConsoleWindowManager.shared.consoleCommandMenu()
     }
 }
+
+private enum CLIInstallError: LocalizedError {
+    case helperNotFound
+    case installFailed(String)
+
+    var errorDescription: String? {
+        switch self {
+        case .helperNotFound:
+            return L10n("The bundled pn helper could not be found.")
+        case .installFailed(let output):
+            return output.isEmpty ? L10n("pn install failed.") : output
+        }
+    }
+}

Planet/Planet.entitlements

@@ -10,6 +10,11 @@
 	<true/>
 	<key>com.apple.security.files.bookmarks.app-scope</key>
 	<true/>
+	<key>com.apple.security.temporary-exception.files.home-relative-path.read-write</key>
+	<array>
+		<string>/.local/</string>
+		<string>/.zprofile</string>
+	</array>
 	<key>com.apple.security.network.client</key>
 	<true/>
 	<key>com.apple.security.network.server</key>

Planet/en.lproj/Localizable.strings

@@ -10,6 +10,15 @@
 
 "Writer" = "";
 "Tools" = "";
+"Install CLI" = "";
+"CLI Already Installed" = "";
+"CLI Installed" = "";
+"Failed to Install CLI" = "";
+"Install the pn CLI to ~/.local/bin so it becomes available in Terminal?" = "";
+"A symbolic link for pn is already installed at ~/.local/bin/pn and can be used in Terminal." = "";
+"A symbolic link for pn has been installed at ~/.local/bin/pn and can be used in Terminal." = "";
+"The bundled pn helper could not be found." = "";
+"pn install failed." = "";
 "Template Browser" = "";
 "Downloads" = "";
 "Publish My Planets" = "";
@@ -270,6 +279,7 @@
 "Add Attachments" = "";
 "Or drag and drop images here." = "";
 "Cancel" = "";
+"Install" = "";
 "Post" = "";
 "Please scan the QR code with your wallet app" = "";
 "Copy URL" = "";
@@ -567,6 +577,7 @@
 "Open Local Gateway" = "Open Local Gateway";
 "Open Permalink in Browser" = "Open Permalink in Browser";
 "Open Shareable Link in Browser" = "Open Shareable Link in Browser";
+"Open Terminal" = "Open Terminal";
 "Open Template Folder in iTerm" = "Open Template Folder in iTerm";
 "Open in Terminal" = "Open in Terminal";
 "Open in Tower" = "Open in Tower";

Planet/versioning.xcconfig

@@ -1 +1 @@
-CURRENT_PROJECT_VERSION = 2823
+CURRENT_PROJECT_VERSION = 2824

PlanetCLI/PNCommandRunner.swift

@@ -170,23 +170,158 @@ final class PNCommandRunner {
 
     private func runInstall(arguments input: PNArguments) throws {
         var arguments = input
-        let to = try arguments.option("--to") ?? "/usr/local/bin"
+        let explicitDestination = try arguments.option("--to")
+        let installDirectory = defaultInstallDirectory()
+        let to = explicitDestination ?? installDirectory.path
         let force = arguments.flag("--force")
         try arguments.ensureNoExtras()
 
         let source = PNAppBridge.executableURL
-        let targetBase = URL(fileURLWithPath: to)
+        let targetBase = URL(fileURLWithPath: NSString(string: to).expandingTildeInPath)
         let target = targetBase.lastPathComponent == "pn" ? targetBase : targetBase.appendingPathComponent("pn", isDirectory: false)
-        if FileManager.default.fileExists(atPath: target.path) {
-            guard force else {
+        let existingSymbolicLink = existingSymbolicLinkDestination(at: target)
+        let targetExists = FileManager.default.fileExists(atPath: target.path) || existingSymbolicLink != nil
+        var didLink = false
+        if targetExists {
+            if force {
+                try FileManager.default.removeItem(at: target)
+            }
+            else if let existingSymbolicLink {
+                // Relink anything that does not already point at this executable,
+                // including stale links left by moved or removed app copies.
+                let destination = symbolicLinkDestinationURL(existingSymbolicLink, relativeTo: target)
+                if destination.resolvingSymlinksInPath().path != source.path {
+                    try FileManager.default.removeItem(at: target)
+                }
+            }
+            else {
                 throw PNError.diskError("\(target.path) already exists. Re-run with --force to replace it.")
             }
-            try FileManager.default.removeItem(at: target)
         }
-        try FileManager.default.createDirectory(at: target.deletingLastPathComponent(), withIntermediateDirectories: true)
-        try FileManager.default.createSymbolicLink(at: target, withDestinationURL: source)
+        if !FileManager.default.fileExists(atPath: target.path) && existingSymbolicLinkDestination(at: target) == nil {
+            try FileManager.default.createDirectory(at: target.deletingLastPathComponent(), withIntermediateDirectories: true)
+            try FileManager.default.createSymbolicLink(at: target, withDestinationURL: source)
+            didLink = true
+        }
+        let shouldUpdateShellProfile = target.deletingLastPathComponent().standardizedFileURL.path == installDirectory.standardizedFileURL.path
+        let didUpdateShellProfile = shouldUpdateShellProfile
+            ? try ensureZshProfileContainsInstallPath(installDirectory)
+            : false
         let result = PNInstallResult(source: source.path, target: target.path)
-        emit(result, human: "Linked \(target.path) -> \(source.path)")
+        var lines = didLink
+            ? ["Linked \(target.path) -> \(source.path)"]
+            : ["Link already up to date at \(target.path) -> \(source.path)"]
+        if didUpdateShellProfile {
+            lines.append("Updated ~/.zprofile to include \(target.deletingLastPathComponent().path) in PATH")
+        }
+        emit(result, human: lines.joined(separator: "\n"))
+    }
+
+    private func defaultInstallDirectory() -> URL {
+        realHomeDirectory().appendingPathComponent(".local/bin", isDirectory: true)
+    }
+
+    // When spawned from the sandboxed app, HOME points to the app container;
+    // resolve the user's real home directory instead.
+    private func realHomeDirectory() -> URL {
+        if let home = getpwuid(getuid())?.pointee.pw_dir {
+            return URL(fileURLWithPath: String(cString: home), isDirectory: true)
+        }
+        return FileManager.default.homeDirectoryForCurrentUser
+    }
+
+    private func existingSymbolicLinkDestination(at url: URL) -> String? {
+        try? FileManager.default.destinationOfSymbolicLink(atPath: url.path)
+    }
+
+    private func symbolicLinkDestinationURL(_ destination: String, relativeTo linkURL: URL) -> URL {
+        let destinationURL = destination.hasPrefix("/")
+            ? URL(fileURLWithPath: destination)
+            : linkURL.deletingLastPathComponent().appendingPathComponent(destination)
+        return destinationURL.standardizedFileURL
+    }
+
+    private func ensureZshProfileContainsInstallPath(_ installDirectory: URL) throws -> Bool {
+        if try zshPATHContainsInstallDirectory(installDirectory) {
+            return false
+        }
+
+        let profileURL = realHomeDirectory()
+            .appendingPathComponent(".zprofile", isDirectory: false)
+        let commentLine = "# Added by Planet to make the pn CLI available in Terminal."
+        let exportLine = #"export PATH="$HOME/.local/bin:$PATH""#
+        var contents = ""
+
+        if FileManager.default.fileExists(atPath: profileURL.path) {
+            contents = try String(contentsOf: profileURL, encoding: .utf8)
+            if contents.contains(exportLine) {
+                return false
+            }
+        }
+
+        if !contents.isEmpty && !contents.hasSuffix("\n") {
+            contents.append("\n")
+        }
+        if !contents.isEmpty {
+            contents.append("\n")
+        }
+        contents.append(commentLine)
+        contents.append("\n")
+        contents.append(exportLine)
+        contents.append("\n")
+
+        try contents.write(to: profileURL, atomically: true, encoding: .utf8)
+        return true
+    }
+
+    private func zshPATHContainsInstallDirectory(_ installDirectory: URL) throws -> Bool {
+        let process = Process()
+        let outputPipe = Pipe()
+        let errorPipe = Pipe()
+        let pathMarkerStart = "__PLANET_PN_PATH_START__"
+        let pathMarkerEnd = "__PLANET_PN_PATH_END__"
+        process.executableURL = URL(fileURLWithPath: "/bin/zsh")
+        process.arguments = [
+            "-lic",
+            #"printf "\n__PLANET_PN_PATH_START__%s__PLANET_PN_PATH_END__\n" "$PATH""#,
+        ]
+        process.environment = [
+            "HOME": realHomeDirectory().path,
+            "LOGNAME": NSUserName(),
+            "PATH": "/usr/bin:/bin:/usr/sbin:/sbin",
+            "SHELL": "/bin/zsh",
+            "USER": NSUserName(),
+        ]
+        process.standardOutput = outputPipe
+        process.standardError = errorPipe
+
+        try process.run()
+        process.waitUntilExit()
+
+        let outputData = outputPipe.fileHandleForReading.readDataToEndOfFile()
+        let errorData = errorPipe.fileHandleForReading.readDataToEndOfFile()
+        let output = String(data: outputData, encoding: .utf8) ?? ""
+        guard process.terminationStatus == 0 else {
+            let error = String(data: errorData, encoding: .utf8)?
+                .trimmingCharacters(in: .whitespacesAndNewlines)
+            throw PNError.diskError(error?.pnNilIfEmpty ?? output.trimmingCharacters(in: .whitespacesAndNewlines))
+        }
+        guard
+            let pathStartRange = output.range(of: pathMarkerStart),
+            let pathEndRange = output.range(of: pathMarkerEnd, range: pathStartRange.upperBound..<output.endIndex)
+        else {
+            throw PNError.diskError("Could not read shell PATH.")
+        }
+        let path = String(output[pathStartRange.upperBound..<pathEndRange.lowerBound])
+        return pathList(path, contains: installDirectory)
+    }
+
+    private func pathList(_ pathList: String, contains targetURL: URL) -> Bool {
+        let targetPath = targetURL.standardizedFileURL.path
+        return pathList.split(separator: ":").contains { item in
+            let expandedPath = NSString(string: String(item)).expandingTildeInPath
+            return URL(fileURLWithPath: expandedPath).standardizedFileURL.path == targetPath
+        }
     }
 
     private func runStatus() throws {
@@ -880,7 +1015,7 @@ final class PNCommandRunner {
             Commands:
               help [command]
               version
-              install [--to /usr/local/bin] [--force]
+              install [--to ~/.local/bin] [--force]
               status
               api status
               api start [--port 8086] [--wait 10]