From f20ad4bd1dd82ba10b72daf1b886f637e1302e8a Mon Sep 17 00:00:00 2001 From: Rolando Santamaria Maso Date: Sun, 8 Nov 2026 18:26:43 +0100 Subject: [PATCH 1/6] feat(updater): CLI install kind and verified, atomic binary install --- Sources/MLXEngine/Updater.swift | 99 ++++- Tests/MLXEngineTests/CLIUpdaterTests.swift | 439 +++++++++++++++++++++ 2 files changed, 537 insertions(+), 1 deletion(-) create mode 100644 Tests/MLXEngineTests/CLIUpdaterTests.swift diff --git a/Sources/MLXEngine/Updater.swift b/Sources/MLXEngine/Updater.swift index d014034..2536fc8 100644 --- a/Sources/MLXEngine/Updater.swift +++ b/Sources/MLXEngine/Updater.swift @@ -50,6 +50,8 @@ public struct UpdateInstall: Equatable, Sendable { case macApp /// `swift run` / an unbundled build: updated with git. case source + /// The standalone `mlxr` command-line binary, replaced in place by `mlxr upgrade`. + case cli } public var kind: Kind @@ -67,10 +69,22 @@ public struct UpdateInstall: Equatable, Sendable { return UpdateInstall(kind: url.pathExtension == "app" ? .macApp : .source, target: url) } - /// The release asset for a version. + /// Works out how a running `mlxr` binary was installed: the real path (symlinks resolved) is the + /// target; a binary inside a `.build` directory is a source build. + public static func detectCLI(executable: URL) -> UpdateInstall { + let url = executable.resolvingSymlinksInPath().standardizedFileURL + return UpdateInstall(kind: url.pathComponents.contains(".build") ? .source : .cli, target: url) + } + + /// The release asset for a version (the app's disk image). public static func assetName(for version: String) -> String { "MLX-Runner-\(version)-macos-arm64.dmg" } + + /// The release asset for a version and install kind. + public static func assetName(for version: String, kind: Kind) -> String { + kind == .cli ? "mlxr-\(version)-macos-arm64.tar.gz" : assetName(for: version) + } } /// The result of a successful `Updater.apply`. @@ -669,3 +683,86 @@ public struct MacAppInstaller: UpdateInstalling { return text } } + + +// MARK: - CLI installer + +/// Extracts `mlxr--macos-arm64/mlxr` from the release tarball with `/usr/bin/tar`, validates it +/// (regular file, size cap, arm64 Mach-O, valid code signature) and swaps it over `target` with one +/// `rename(2)`. Everything it creates in `stage` is removed again, on success and on failure. +public struct CLIInstaller: UpdateInstalling { + public static let defaultMaxBinaryBytes: Int = 256 << 20 + public var maxBinaryBytes: Int + + public init(maxBinaryBytes: Int = CLIInstaller.defaultMaxBinaryBytes) { + self.maxBinaryBytes = maxBinaryBytes + } + + public func install(package: URL, version: String, target: URL, stage: URL) async throws { + // tar and codesign block: keep them off the cooperative thread pool. + try await withCheckedThrowingContinuation { (c: CheckedContinuation) in + DispatchQueue.global(qos: .userInitiated).async { + c.resume(with: Result { try installSync(package: package, version: version, target: target, stage: stage) }) + } + } + } + + func installSync(package: URL, version: String, target: URL, stage: URL) throws { + let folder = "mlxr-\(version)-macos-arm64" + let member = "\(folder)/mlxr" + try checkListing(package: package, folder: folder, member: member) + + let work = stage.appendingPathComponent("extract", isDirectory: true) + try FileManager.default.createDirectory(at: work, withIntermediateDirectories: false) + defer { try? FileManager.default.removeItem(at: work) } + try MacAppInstaller.run("/usr/bin/tar", ["-xzf", package.path, "-C", work.path, "--", member]) + + let staged = work.appendingPathComponent(member) + try validate(staged) + guard chmod(staged.path, 0o755) == 0 else { + throw UpdateError("Could not make the new mlxr executable: \(String(cString: strerror(errno))).") + } + guard rename(staged.path, target.path) == 0 else { + throw UpdateError("Could not replace \(target.path): \(String(cString: strerror(errno))).") + } + } + + /// Every archive member must live under the release folder (no absolute or `..` paths), and the + /// binary must be there exactly once. Other members (LICENSE) are never extracted. + func checkListing(package: URL, folder: String, member: String) throws { + let listing = try MacAppInstaller.run("/usr/bin/tar", ["-tzf", package.path]) + let names = listing.split(separator: "\n", omittingEmptySubsequences: true).map(String.init) + var found = 0 + for name in names { + let parts = name.split(separator: "/", omittingEmptySubsequences: false) + guard !name.hasPrefix("/"), !parts.contains(".."), name.hasPrefix(folder + "/") else { + throw UpdateError("The release archive has an unexpected entry: \(name.prefix(80)).") + } + if name == member { found += 1 } + } + guard found == 1 else { throw UpdateError("The release archive has no \(member).") } + } + + /// A regular file (never a link) under the size cap, arm64 Mach-O, validly code signed. + func validate(_ file: URL) throws { + var st = stat() + guard lstat(file.path, &st) == 0, (st.st_mode & S_IFMT) == S_IFREG else { + throw UpdateError("The new mlxr is not a regular file.") + } + guard st.st_size <= Int64(maxBinaryBytes) else { throw UpdateError("The new mlxr is too large.") } + guard st.st_size >= 8, let handle = try? FileHandle(forReadingFrom: file) else { + throw UpdateError("The new mlxr is not an arm64 executable.") + } + let head = (try? handle.read(upToCount: 8)) ?? Data() + try? handle.close() + // MH_MAGIC_64 (CF FA ED FE), then CPU_TYPE_ARM64 (0x0100000C), both little-endian. + guard Array(head) == [0xCF, 0xFA, 0xED, 0xFE, 0x0C, 0x00, 0x00, 0x01] else { + throw UpdateError("The new mlxr is not an arm64 executable.") + } + do { + try MacAppInstaller.run("/usr/bin/codesign", ["--verify", "--strict", file.path]) + } catch let e as UpdateError { + throw UpdateError("The new mlxr's code signature is invalid: \(e.message)") + } + } +} diff --git a/Tests/MLXEngineTests/CLIUpdaterTests.swift b/Tests/MLXEngineTests/CLIUpdaterTests.swift new file mode 100644 index 0000000..24bfc95 --- /dev/null +++ b/Tests/MLXEngineTests/CLIUpdaterTests.swift @@ -0,0 +1,439 @@ +import Foundation +import Testing +@testable import MLXEngine + +// SL01: the `.cli` install kind, its asset name, and CLIInstaller's extraction and validation. +// Everything is local: real tarballs are built with /usr/bin/tar in a temporary directory. + +// MARK: - Fixtures + +private let testVersion = "9.9.9" +private let memberDir = "mlxr-\(testVersion)-macos-arm64" +private let oldBytes = Data("old-binary".utf8) + +/// A small arm64 Mach-O executable, ad-hoc signed, built once with swiftc. Prints "new-binary". +private let signedBinary: Data? = { + let dir = FileManager.default.temporaryDirectory.appendingPathComponent("mlxr-cli-fixture-\(UUID().uuidString)") + defer { try? FileManager.default.removeItem(at: dir) } + do { + try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true) + let src = dir.appendingPathComponent("stub.swift") + try Data("print(\"new-binary\")\n".utf8).write(to: src) + let out = dir.appendingPathComponent("stub") + try MacAppInstaller.run("/usr/bin/swiftc", ["-o", out.path, src.path]) + try MacAppInstaller.run("/usr/bin/codesign", ["-f", "-s", "-", out.path]) + return try Data(contentsOf: out) + } catch { return nil } +}() + +private func requireBinary() throws -> Data { + try #require(signedBinary, "swiftc/codesign unavailable: cannot build a test Mach-O") +} + +private func tamper(_ data: Data) -> Data { + var d = data + d[d.count / 2] ^= 0xFF // inside the signed pages, before the signature blob + return d +} + +private func unsigned(_ data: Data) throws -> Data { + let dir = FileManager.default.temporaryDirectory.appendingPathComponent("mlxr-cli-unsigned-\(UUID().uuidString)") + try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true) + defer { try? FileManager.default.removeItem(at: dir) } + let f = dir.appendingPathComponent("b") + try data.write(to: f) + try MacAppInstaller.run("/usr/bin/codesign", ["--remove-signature", f.path]) + return try Data(contentsOf: f) +} + +/// Mach-O header bytes: magic, cputype, then padding. +private func header(magic: [UInt8], cpu: [UInt8], total: Int = 4096) -> Data { + var d = Data(magic + cpu) + d.append(Data(count: max(0, total - d.count))) + return d +} + +enum Member { + case file(Data, mode: UInt16 = 0o755) + case symlink(String) +} + +/// A temp area with a target directory holding the old binary, a stage directory and a tarball. +private struct Area { + let root: URL + let targetDir: URL + let target: URL + let stage: URL + var tarball: URL { stage.appendingPathComponent("mlxr-\(testVersion)-macos-arm64.tar.gz") } + + init() throws { + root = FileManager.default.temporaryDirectory.appendingPathComponent("mlxr-cli-test-\(UUID().uuidString)", isDirectory: true) + targetDir = root.appendingPathComponent("bin", isDirectory: true) + target = targetDir.appendingPathComponent("mlxr") + stage = targetDir.appendingPathComponent(".mlxrunner-update-TEST", isDirectory: true) + try FileManager.default.createDirectory(at: stage, withIntermediateDirectories: true) + try oldBytes.write(to: target) + chmod(target.path, 0o644) + } + + func cleanup() { try? FileManager.default.removeItem(at: root) } + + /// Builds `tarball` with /usr/bin/tar. Each (stored, archived) pair is written to a scratch tree + /// under `stored`, then archived under the name `archived` (via `-s` when they differ). + func makeTarball(_ members: [(stored: String, archived: String, member: Member)]) throws { + let src = root.appendingPathComponent("src-\(UUID().uuidString)", isDirectory: true) + try FileManager.default.createDirectory(at: src, withIntermediateDirectories: true) + defer { try? FileManager.default.removeItem(at: src) } + var args = ["-P", "-czf", tarball.path, "-C", src.path] + var names: [String] = [] + for m in members { + let f = src.appendingPathComponent(m.stored) + try FileManager.default.createDirectory(at: f.deletingLastPathComponent(), withIntermediateDirectories: true) + switch m.member { + case .file(let data, let mode): + try data.write(to: f) + chmod(f.path, mode_t(mode)) + case .symlink(let dest): + try FileManager.default.createSymbolicLink(atPath: f.path, withDestinationPath: dest) + } + if m.stored != m.archived { args += ["-s", "|^\(m.stored)$|\(m.archived)|"] } + names.append(m.stored) + } + try MacAppInstaller.run("/usr/bin/tar", args + names) // options first, then the members + } + + /// The release layout: `mlxr--macos-arm64/mlxr` plus LICENSE. + func makeRelease(binary: Data, withLicense: Bool = true) throws { + var members: [(String, String, Member)] = [("\(memberDir)/mlxr", "\(memberDir)/mlxr", .file(binary))] + if withLicense { members.append(("\(memberDir)/LICENSE", "\(memberDir)/LICENSE", .file(Data("MIT".utf8), mode: 0o644))) } + try makeTarball(members.map { (stored: $0.0, archived: $0.1, member: $0.2) }) + } + + func listing() -> [String] { + ((try? FileManager.default.contentsOfDirectory(atPath: targetDir.path)) ?? []).sorted() + } + + func stageListing() -> [String] { + ((try? FileManager.default.contentsOfDirectory(atPath: stage.path)) ?? []).sorted() + } + + func install(_ installer: CLIInstaller = CLIInstaller()) async throws { + try await installer.install(package: tarball, version: testVersion, target: target, stage: stage) + } + + /// The install must throw an UpdateError and leave target, its directory and the stage as they were. + func expectRejected(_ installer: CLIInstaller = CLIInstaller(), sourceLocation: SourceLocation = #_sourceLocation) async { + var thrown: Error? + do { try await install(installer) } catch { thrown = error } + #expect(thrown is UpdateError, "expected an UpdateError, got \(String(describing: thrown))", sourceLocation: sourceLocation) + #expect((try? Data(contentsOf: target)) == oldBytes, "target changed", sourceLocation: sourceLocation) + #expect(listing() == [".mlxrunner-update-TEST", "mlxr"], "stray files next to the target: \(listing())", sourceLocation: sourceLocation) + #expect(stageListing() == [tarball.lastPathComponent], "stage not cleaned: \(stageListing())", sourceLocation: sourceLocation) + } +} + +// MARK: - AC-1: kind detection and asset name + +@Suite("CLI update: kind and asset name") +struct CLIKindTests { + @Test func installedBinaryIsCLI() { + let i = UpdateInstall.detectCLI(executable: URL(fileURLWithPath: "/usr/local/bin/mlxr")) + #expect(i.kind == .cli) + #expect(i.target.path == "/usr/local/bin/mlxr") + } + + @Test func buildDirectoryIsSource() { + for path in ["/Users/me/mlx-runner/.build/arm64-apple-macosx/release/mlxr", "/Users/me/mlx-runner/.build/debug/mlxr"] { + #expect(UpdateInstall.detectCLI(executable: URL(fileURLWithPath: path)).kind == .source, "\(path)") + } + } + + @Test func buildLookalikeIsNotSource() { + for path in ["/Users/me/my.build/bin/mlxr", "/Users/me/.builds/mlxr", "/opt/x.build/mlxr"] { + #expect(UpdateInstall.detectCLI(executable: URL(fileURLWithPath: path)).kind == .cli, "\(path)") + } + } + + @Test func symlinkIsResolvedToTheRealFile() throws { + let a = try Area() + defer { a.cleanup() } + let link = a.root.appendingPathComponent("mlxr-link") + try FileManager.default.createSymbolicLink(atPath: link.path, withDestinationPath: a.target.path) + let i = UpdateInstall.detectCLI(executable: link) + #expect(i.kind == .cli) + #expect(i.target.resolvingSymlinksInPath().path == a.target.resolvingSymlinksInPath().path) + #expect(i.target.lastPathComponent == "mlxr", "target is the file the link points to, not the link") + #expect(i.target.path != link.path) + } + + @Test func symlinkIntoABuildDirectoryIsSource() throws { + let a = try Area() + defer { a.cleanup() } + let build = a.root.appendingPathComponent("repo/.build/release", isDirectory: true) + try FileManager.default.createDirectory(at: build, withIntermediateDirectories: true) + let real = build.appendingPathComponent("mlxr") + try oldBytes.write(to: real) + let link = a.root.appendingPathComponent("bin/mlxr-dev") + try FileManager.default.createSymbolicLink(atPath: link.path, withDestinationPath: real.path) + #expect(UpdateInstall.detectCLI(executable: link).kind == .source) + } + + @Test func cliAssetName() { + #expect(UpdateInstall.assetName(for: "2.0.1", kind: .cli) == "mlxr-2.0.1-macos-arm64.tar.gz") + } + + @Test func appAssetNameIsUnchanged() { + #expect(UpdateInstall.assetName(for: "1.2.0") == "MLX-Runner-1.2.0-macos-arm64.dmg") + #expect(UpdateInstall.assetName(for: "1.2.0", kind: .macApp) == "MLX-Runner-1.2.0-macos-arm64.dmg") + } + + @Test func appDetectionIsUnchanged() { + #expect(UpdateInstall.detect(bundleURL: URL(fileURLWithPath: "/Applications/MLX Runner.app")).kind == .macApp) + #expect(UpdateInstall.detect(bundleURL: URL(fileURLWithPath: "/Users/me/mlx-runner/.build/debug")).kind == .source) + } +} + +// MARK: - AC-2: a valid tarball installs atomically + +@Suite("CLI update: install") +struct CLIInstallTests { + @Test func replacesTheTargetWithTheNewBinary() async throws { + let bin = try requireBinary() + let a = try Area() + defer { a.cleanup() } + try a.makeRelease(binary: bin) + try await a.install() + #expect(try Data(contentsOf: a.target) == bin) + let mode = (try FileManager.default.attributesOfItem(atPath: a.target.path)[.posixPermissions] as? NSNumber)?.intValue + #expect(mode == 0o755) + } + + @Test func installedBinaryRuns() async throws { + let bin = try requireBinary() + let a = try Area() + defer { a.cleanup() } + try a.makeRelease(binary: bin) + try await a.install() + let out = try MacAppInstaller.run(a.target.path, []) + #expect(out.trimmingCharacters(in: .whitespacesAndNewlines) == "new-binary") + } + + @Test func leavesNothingBehindButTheTarball() async throws { + let bin = try requireBinary() + let a = try Area() + defer { a.cleanup() } + try a.makeRelease(binary: bin) + try await a.install() + #expect(try Data(contentsOf: a.target) == bin) + #expect(a.listing() == [".mlxrunner-update-TEST", "mlxr"], "\(a.listing())") + #expect(a.stageListing() == [a.tarball.lastPathComponent], "\(a.stageListing())") + } + + @Test func releaseWithoutLicenseInstalls() async throws { + let bin = try requireBinary() + let a = try Area() + defer { a.cleanup() } + try a.makeRelease(binary: bin, withLicense: false) + try await a.install() + #expect(try Data(contentsOf: a.target) == bin) + } + + @Test func licenseIsNeverInstalled() async throws { + let bin = try requireBinary() + let a = try Area() + defer { a.cleanup() } + try a.makeRelease(binary: bin) + try await a.install() + #expect(try Data(contentsOf: a.target) == bin) + #expect(!a.listing().contains("LICENSE")) + #expect(!a.stageListing().contains(memberDir)) + } + + @Test func aRestrictiveModeInTheArchiveStillEndsAs755() async throws { + let bin = try requireBinary() + let a = try Area() + defer { a.cleanup() } + try a.makeTarball([(stored: "\(memberDir)/mlxr", archived: "\(memberDir)/mlxr", member: .file(bin, mode: 0o600))]) + try await a.install() + let mode = (try FileManager.default.attributesOfItem(atPath: a.target.path)[.posixPermissions] as? NSNumber)?.intValue + #expect(mode == 0o755) + } + + @Test func aTargetThatCannotBeReplacedKeepsTheOldBinary() async throws { + // rename(2) of a file over a directory fails: the install must report it and clean up. + let bin = try requireBinary() + let a = try Area() + defer { a.cleanup() } + try FileManager.default.removeItem(at: a.target) + try FileManager.default.createDirectory(at: a.target, withIntermediateDirectories: false) + try oldBytes.write(to: a.target.appendingPathComponent("keep")) + try a.makeRelease(binary: bin) + var thrown: Error? + do { try await a.install() } catch { thrown = error } + #expect(thrown is UpdateError) + #expect(try Data(contentsOf: a.target.appendingPathComponent("keep")) == oldBytes) + #expect(a.stageListing() == [a.tarball.lastPathComponent], "\(a.stageListing())") + } +} + +// MARK: - AC-3: hostile archive layouts + +@Suite("CLI update: archive layout") +struct CLILayoutTests { + @Test func symlinkMemberIsRejected() async throws { + let a = try Area() + defer { a.cleanup() } + try a.makeTarball([(stored: "\(memberDir)/mlxr", archived: "\(memberDir)/mlxr", member: .symlink("/bin/ls"))]) + await a.expectRejected() + } + + @Test func pathWithDotDotIsRejected() async throws { + let bin = try requireBinary() + let a = try Area() + defer { a.cleanup() } + try a.makeTarball([(stored: "zz/mlxr", archived: "\(memberDir)/../mlxr", member: .file(bin))]) + let listing = try MacAppInstaller.run("/usr/bin/tar", ["-tzf", a.tarball.path]) + try #require(listing.contains(".."), "fixture must really contain a .. path: \(listing)") + await a.expectRejected() + } + + @Test func dotDotMemberNextToTheRealOneIsRejected() async throws { + let bin = try requireBinary() + let a = try Area() + defer { a.cleanup() } + try a.makeTarball([ + (stored: "\(memberDir)/mlxr", archived: "\(memberDir)/mlxr", member: .file(bin)), + (stored: "zz/evil", archived: "\(memberDir)/../../evil", member: .file(Data("x".utf8))), + ]) + await a.expectRejected() + #expect(!FileManager.default.fileExists(atPath: a.root.appendingPathComponent("evil").path)) + } + + @Test func absolutePathMemberIsRejected() async throws { + let bin = try requireBinary() + let a = try Area() + defer { a.cleanup() } + let abs = a.root.appendingPathComponent("abs").path + "/mlxr" + try a.makeTarball([(stored: "zz/mlxr", archived: abs, member: .file(bin))]) + await a.expectRejected() + #expect(!FileManager.default.fileExists(atPath: abs)) + } + + @Test func extraMemberOutsideTheReleaseFolderIsRejected() async throws { + let bin = try requireBinary() + let a = try Area() + defer { a.cleanup() } + try a.makeTarball([ + (stored: "\(memberDir)/mlxr", archived: "\(memberDir)/mlxr", member: .file(bin)), + (stored: "other/payload", archived: "other/payload", member: .file(Data("x".utf8))), + ]) + await a.expectRejected() + } + + @Test func memberFromAnotherVersionFolderIsRejected() async throws { + let bin = try requireBinary() + let a = try Area() + defer { a.cleanup() } + try a.makeTarball([(stored: "mlxr-1.0.0-macos-arm64/mlxr", archived: "mlxr-1.0.0-macos-arm64/mlxr", member: .file(bin))]) + await a.expectRejected() + } + + @Test func archiveWithoutTheBinaryIsRejected() async throws { + let a = try Area() + defer { a.cleanup() } + try a.makeTarball([(stored: "\(memberDir)/LICENSE", archived: "\(memberDir)/LICENSE", member: .file(Data("MIT".utf8)))]) + await a.expectRejected() + } + + @Test func notATarballIsRejected() async throws { + let a = try Area() + defer { a.cleanup() } + try Data("not a tarball at all".utf8).write(to: a.tarball) + await a.expectRejected() + } +} + +// MARK: - AC-4: Mach-O arm64 check and size cap + +@Suite("CLI update: binary validation") +struct CLIValidationTests { + private static let magic: [UInt8] = [0xCF, 0xFA, 0xED, 0xFE] + private static let arm64: [UInt8] = [0x0C, 0x00, 0x00, 0x01] + private static let x86_64: [UInt8] = [0x07, 0x00, 0x00, 0x01] + + private func rejects(_ data: Data, sourceLocation: SourceLocation = #_sourceLocation) async throws { + let a = try Area() + defer { a.cleanup() } + try a.makeRelease(binary: data) + await a.expectRejected(sourceLocation: sourceLocation) + } + + @Test func wrongMagicIsRejected() async throws { + try await rejects(header(magic: [0x7F, 0x45, 0x4C, 0x46], cpu: Self.arm64)) // ELF + try await rejects(Data("#!/bin/sh\necho pwned\n".utf8)) + } + + @Test func fatBinaryIsRejected() async throws { + try await rejects(header(magic: [0xCA, 0xFE, 0xBA, 0xBE], cpu: [0x00, 0x00, 0x00, 0x02])) + try await rejects(header(magic: [0xBE, 0xBA, 0xFE, 0xCA], cpu: [0x02, 0x00, 0x00, 0x00])) + } + + @Test func x86_64BinaryIsRejected() async throws { + try await rejects(header(magic: Self.magic, cpu: Self.x86_64)) + } + + @Test func emptyMemberIsRejected() async throws { + try await rejects(Data()) + } + + @Test func truncatedHeaderIsRejected() async throws { + try await rejects(Data(Self.magic)) + try await rejects(Data(Self.magic + [0x0C])) + } + + @Test func defaultSizeCapIs256MiB() { + #expect(CLIInstaller.defaultMaxBinaryBytes == 256 << 20) + #expect(CLIInstaller().maxBinaryBytes == 256 << 20) + } + + @Test func memberOverTheCapIsRejected() async throws { + let bin = try requireBinary() + let a = try Area() + defer { a.cleanup() } + try a.makeRelease(binary: bin) + await a.expectRejected(CLIInstaller(maxBinaryBytes: bin.count - 1)) + } + + @Test func memberExactlyAtTheCapInstalls() async throws { + let bin = try requireBinary() + let a = try Area() + defer { a.cleanup() } + try a.makeRelease(binary: bin) + try await a.install(CLIInstaller(maxBinaryBytes: bin.count)) + #expect(try Data(contentsOf: a.target) == bin) + } +} + +// MARK: - AC-5: code signature + +@Suite("CLI update: code signature") +struct CLISignatureTests { + @Test func unsignedBinaryIsRejected() async throws { + let bin = try unsigned(try requireBinary()) + // still a valid arm64 Mach-O: only the signature check can stop it + #expect(Array(bin.prefix(4)) == [0xCF, 0xFA, 0xED, 0xFE]) + let a = try Area() + defer { a.cleanup() } + try a.makeRelease(binary: bin) + await a.expectRejected() + } + + @Test func tamperedBinaryIsRejected() async throws { + let bin = tamper(try requireBinary()) + #expect(Array(bin.prefix(4)) == [0xCF, 0xFA, 0xED, 0xFE]) + let a = try Area() + defer { a.cleanup() } + try a.makeRelease(binary: bin) + await a.expectRejected() + } +} From 465879888b7a9caf07eca521c57353a27c6a3253 Mon Sep 17 00:00:00 2001 From: Rolando Santamaria Maso Date: Sun, 8 Nov 2026 18:38:00 +0100 Subject: [PATCH 2/6] feat(updater): verified CLI upgrade flow with up-to-date, source and permission checks --- Sources/MLXEngine/Updater.swift | 41 ++- .../MLXEngineTests/CLIUpdateApplyTests.swift | 336 ++++++++++++++++++ 2 files changed, 365 insertions(+), 12 deletions(-) create mode 100644 Tests/MLXEngineTests/CLIUpdateApplyTests.swift diff --git a/Sources/MLXEngine/Updater.swift b/Sources/MLXEngine/Updater.swift index 2536fc8..6ae84ec 100644 --- a/Sources/MLXEngine/Updater.swift +++ b/Sources/MLXEngine/Updater.swift @@ -57,10 +57,13 @@ public struct UpdateInstall: Equatable, Sendable { public var kind: Kind /// The `.app` bundle that gets replaced. public var target: URL + /// The target is the standalone `mlxr` binary (installed or a source build), not an app bundle. + public var isCommandLine: Bool - public init(kind: Kind, target: URL) { + public init(kind: Kind, target: URL, isCommandLine: Bool? = nil) { self.kind = kind self.target = target + self.isCommandLine = isCommandLine ?? (kind == .cli) } /// Works out how the running app was installed from its bundle location. @@ -73,7 +76,7 @@ public struct UpdateInstall: Equatable, Sendable { /// target; a binary inside a `.build` directory is a source build. public static func detectCLI(executable: URL) -> UpdateInstall { let url = executable.resolvingSymlinksInPath().standardizedFileURL - return UpdateInstall(kind: url.pathComponents.contains(".build") ? .source : .cli, target: url) + return UpdateInstall(kind: url.pathComponents.contains(".build") ? .source : .cli, target: url, isCommandLine: true) } /// The release asset for a version (the app's disk image). @@ -314,14 +317,24 @@ public actor Updater { } private func cannotInstall(_ r: Release) -> String? { - if install.kind == .source { return "Running from source: update with git pull." } - let name = UpdateInstall.assetName(for: r.version) + if install.kind == .source { + return install.isCommandLine ? "mlxr is running from a source build; update it with git pull" + : "Running from source: update with git pull." + } + let name = UpdateInstall.assetName(for: r.version, kind: install.kind) if r.assets[name] == nil { return "This release has no build for this Mac (\(name))." } if r.assets["SHA256SUMS"] == nil || r.assets["SHA256SUMS.sig"] == nil { return "This release isn't signed, so it can't be installed automatically." } if Self.publicKey(fromBase64: publicKeyBase64) == nil { return "This build has no update signing key." } let path = install.target.path + if install.kind == .cli { + // The binary is replaced by a rename in its directory, so the directory must be writable. + if !FileManager.default.isWritableFile(atPath: install.target.deletingLastPathComponent().path) { + return "cannot replace \(path) (permission denied); run: sudo mlxr upgrade" + } + return nil + } if path.contains("/AppTranslocation/") || path.hasPrefix("/Volumes/") { return "Move MLX Runner to the Applications folder to update it." } @@ -343,9 +356,9 @@ public actor Updater { progress(.checking) let info = try await check(force: true) - guard info.available, let release = cached?.release else { throw UpdateError("MLX Runner is already up to date.") } + guard info.available, let release = cached?.release else { throw UpdateError(install.isCommandLine ? "mlxr is already up to date." : "MLX Runner is already up to date.") } guard info.canInstall else { throw UpdateError(info.reason ?? "This update can't be installed automatically.") } - let name = UpdateInstall.assetName(for: release.version) + let name = UpdateInstall.assetName(for: release.version, kind: install.kind) guard let assetURL = release.assets[name], let sumsURL = release.assets["SHA256SUMS"], let sigURL = release.assets["SHA256SUMS.sig"] else { throw UpdateError("The release is missing files.") } @@ -474,13 +487,17 @@ public actor Updater { let session = URLSession(configuration: configuration, delegate: delegate, delegateQueue: queue) defer { session.finishTasksAndInvalidate() } let task = session.dataTask(with: request) - try await withTaskCancellationHandler { - try await withCheckedThrowingContinuation { (c: CheckedContinuation) in - delegate.continuation = c - task.resume() + do { + try await withTaskCancellationHandler { + try await withCheckedThrowingContinuation { (c: CheckedContinuation) in + delegate.continuation = c + task.resume() + } + } onCancel: { + task.cancel() } - } onCancel: { - task.cancel() + } catch let e as URLError where e.code != .cancelled { + throw UpdateError("Network error: \(e.localizedDescription)") } } } diff --git a/Tests/MLXEngineTests/CLIUpdateApplyTests.swift b/Tests/MLXEngineTests/CLIUpdateApplyTests.swift new file mode 100644 index 0000000..438aa65 --- /dev/null +++ b/Tests/MLXEngineTests/CLIUpdateApplyTests.swift @@ -0,0 +1,336 @@ +import CryptoKit +import Foundation +import Testing +@testable import MLXEngine + +// SL02: Updater.apply for the `.cli` kind. No network: a URLProtocol stub serves the release API, +// SHA256SUMS, SHA256SUMS.sig and a real tarball (built with /usr/bin/tar); a throwaway Ed25519 key +// stands in for UpdateKey. + +private let api = "https://api.github.com/repos/BackendStack21/mlx-runner/releases/latest" +private let dl = "https://github.com/BackendStack21/mlx-runner/releases/download" +private let oldBytes = Data("old-binary".utf8) + +private func hex(_ d: Data) -> String { SHA256.hash(data: d).map { String(format: "%02x", $0) }.joined() } + +private func cliAsset(_ version: String) -> String { UpdateInstall.assetName(for: version, kind: .cli) } + +/// A temp `bin/` directory holding the installed (old) `mlxr`. +private struct Bin { + let root: URL + let dir: URL + let target: URL + var install: UpdateInstall { UpdateInstall(kind: .cli, target: target) } + + init() throws { + root = FileManager.default.temporaryDirectory.appendingPathComponent("mlxr-apply-\(UUID().uuidString)", isDirectory: true) + dir = root.appendingPathComponent("bin", isDirectory: true) + target = dir.appendingPathComponent("mlxr") + try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true) + try oldBytes.write(to: target) + chmod(target.path, 0o755) + } + + func cleanup() { + chmod(dir.path, 0o755) + try? FileManager.default.removeItem(at: root) + } + + func listing() -> [String] { ((try? FileManager.default.contentsOfDirectory(atPath: dir.path)) ?? []).sorted() } + var targetBytes: Data? { try? Data(contentsOf: target) } +} + +/// A complete, validly signed CLI release served by the stub. `tarball` is a real .tar.gz. +private struct CLIRelease { + let version: String + let key = Curve25519.Signing.PrivateKey() + let tarball: Data + let sums: Data + let sig: Data + var routes: [String: UpdateStub.Route] + var publicKey: String { key.publicKey.rawRepresentation.base64EncodedString() } + var tarballURL: String { "\(dl)/v\(version)/\(cliAsset(version))" } + + init(version: String) throws { + self.version = version + let tmp = FileManager.default.temporaryDirectory.appendingPathComponent("mlxr-apply-tar-\(UUID().uuidString)", isDirectory: true) + defer { try? FileManager.default.removeItem(at: tmp) } + let folder = "mlxr-\(version)-macos-arm64" + try FileManager.default.createDirectory(at: tmp.appendingPathComponent(folder), withIntermediateDirectories: true) + try Data("stand-in for the new mlxr".utf8).write(to: tmp.appendingPathComponent("\(folder)/mlxr")) + try Data("MIT".utf8).write(to: tmp.appendingPathComponent("\(folder)/LICENSE")) + let out = tmp.appendingPathComponent("a.tar.gz") + try MacAppInstaller.run("/usr/bin/tar", ["-czf", out.path, "-C", tmp.path, folder]) + tarball = try Data(contentsOf: out) + let name = cliAsset(version) + // The app's disk image is listed too, as in a real release; it must be ignored. + sums = Data("\(hex(tarball)) \(name)\n\(String(repeating: "b", count: 64)) \(UpdateInstall.assetName(for: version))\n".utf8) + sig = try key.signature(for: sums) + let names = [cliAsset(version), UpdateInstall.assetName(for: version), "SHA256SUMS", "SHA256SUMS.sig"] + let json: [String: Any] = [ + "tag_name": "v\(version)", "html_url": "https://github.com/BackendStack21/mlx-runner/releases/tag/v\(version)", + "body": "notes", "draft": false, "prerelease": false, + "assets": names.map { ["name": $0, "browser_download_url": "\(dl)/v\(version)/\($0)"] }, + ] + routes = [ + api: .body(200, try JSONSerialization.data(withJSONObject: json)), + "\(dl)/v\(version)/\(name)": .body(200, tarball), + "\(dl)/v\(version)/SHA256SUMS": .body(200, sums), + "\(dl)/v\(version)/SHA256SUMS.sig": .body(200, sig), + ] + } +} + +private func makeUpdater(_ release: CLIRelease, bin: Bin, current: String, install: UpdateInstall? = nil, + installer: any UpdateInstalling = StubInstaller(), + routes: [String: UpdateStub.Route]? = nil) -> (Updater, String) { + let (config, id) = UpdateStub.configuration(routes ?? release.routes) + return (Updater(currentVersion: current, publicKey: release.publicKey, install: install ?? bin.install, + configuration: config, installer: installer), id) +} + +/// Installer that fails after the updater downloaded the package. +private struct FailingInstaller: UpdateInstalling { + func install(package: URL, version: String, target: URL, stage: URL) async throws { + try Data("partial".utf8).write(to: stage.appendingPathComponent("partial")) + throw UpdateError("install failed on purpose") + } +} + +/// Fails every request like an unreachable or hung host. +final class UnreachableStub: URLProtocol, @unchecked Sendable { + override class func canInit(with request: URLRequest) -> Bool { true } + override class func canonicalRequest(for request: URLRequest) -> URLRequest { request } + override func startLoading() { + let code: URLError.Code = request.value(forHTTPHeaderField: "X-Fail") == "timeout" ? .timedOut : .cannotFindHost + client?.urlProtocol(self, didFailWithError: URLError(code)) + } + override func stopLoading() {} +} + +@Suite("CLI update: apply") +struct CLIUpdateApplyTests { + // MARK: happy path + + @Test func downloadsVerifiesAndHandsTheTarballToTheInstaller() async throws { + let bin = try Bin() + defer { bin.cleanup() } + let r = try CLIRelease(version: "2.0.1") + let installer = StubInstaller() + let (u, id) = makeUpdater(r, bin: bin, current: "2.0.0", installer: installer) + let info = try await u.check() + #expect(info.available && info.canInstall, "reason: \(info.reason ?? "nil")") + let log = PhaseLog() + let applied = try await u.apply { log.add($0) } + #expect(applied == AppliedUpdate(version: "2.0.1", target: bin.target)) + let call = try #require(installer.calls.first) + #expect(installer.calls.count == 1) + #expect(call.package.lastPathComponent == "mlxr-2.0.1-macos-arm64.tar.gz") + #expect(call.bytes == r.tarball) + #expect(call.version == "2.0.1") + #expect(call.stage.deletingLastPathComponent() == bin.dir, "staging is next to the target") + #expect(!FileManager.default.fileExists(atPath: call.stage.path), "staging removed") + // The app's disk image is never downloaded. + #expect(!UpdateStub.requests(id).contains { $0.hasSuffix(".dmg") }) + #expect(bin.listing() == ["mlxr"]) + let coarse = log.phases.filter { if case .download = $0 { false } else { true } } + #expect(coarse == [.checking, .signature, .checksum, .install, .done("2.0.1")]) + } + + // MARK: AC-10: up to date and version ordering + + @Test func upToDateDownloadsNothing() async throws { + let bin = try Bin() + defer { bin.cleanup() } + let r = try CLIRelease(version: "2.0.0") + let installer = StubInstaller() + let (u, id) = makeUpdater(r, bin: bin, current: "2.0.0", installer: installer) + let info = try await u.check(force: true) + #expect(info.latest == "2.0.0") + #expect(!info.available) + await #expect(throws: UpdateError.self) { try await u.apply() } + #expect(UpdateStub.requests(id).allSatisfy { $0 == api }, "only the release API was asked: \(UpdateStub.requests(id))") + #expect(installer.calls.isEmpty) + #expect(bin.listing() == ["mlxr"]) + #expect(bin.targetBytes == oldBytes) + } + + @Test func olderReleaseIsNotAnUpdate() async throws { + let bin = try Bin() + defer { bin.cleanup() } + let r = try CLIRelease(version: "2.0.9") + let installer = StubInstaller() + let (u, id) = makeUpdater(r, bin: bin, current: "2.0.10", installer: installer) + #expect(try await u.check(force: true).available == false, "2.0.9 is older than 2.0.10") + await #expect(throws: UpdateError.self) { try await u.apply() } + #expect(UpdateStub.requests(id).allSatisfy { $0 == api }) + #expect(installer.calls.isEmpty) + } + + @Test func multiDigitPatchIsNewer() async throws { + let bin = try Bin() + defer { bin.cleanup() } + let r = try CLIRelease(version: "2.0.10") + let installer = StubInstaller() + let (u, _) = makeUpdater(r, bin: bin, current: "2.0.9", installer: installer) + let info = try await u.check(force: true) + #expect(info.available, "2.0.10 is newer than 2.0.9") + #expect(info.canInstall, "reason: \(info.reason ?? "nil")") + let applied = try await u.apply() + #expect(applied.version == "2.0.10") + #expect(installer.calls.first?.package.lastPathComponent == "mlxr-2.0.10-macos-arm64.tar.gz") + } + + @Test func networkFailuresAreUpdateErrors() async throws { + let bin = try Bin() + defer { bin.cleanup() } + let r = try CLIRelease(version: "2.0.1") + // GitHub answers 5xx. + for status in [500, 503] { + let (u, _) = makeUpdater(r, bin: bin, current: "2.0.0", routes: [api: .body(status, Data())]) + await #expect(throws: UpdateError("Update check failed: GitHub answered \(status).")) { try await u.check(force: true) } + await #expect(throws: UpdateError("Update check failed: GitHub answered \(status).")) { try await u.apply() } + } + // The release file download answers 5xx. + var routes = r.routes + routes[r.tarballURL] = .body(502, Data()) + let installer = StubInstaller() + let (u, _) = makeUpdater(r, bin: bin, current: "2.0.0", installer: installer, routes: routes) + await #expect(throws: UpdateError.self) { try await u.apply() } + #expect(installer.calls.isEmpty) + #expect(bin.listing() == ["mlxr"], "staging removed: \(bin.listing())") + // Timeouts and unreachable hosts surface as UpdateError, not as a raw URLError. + for header in ["timeout", "unreachable"] { + let config = URLSessionConfiguration.ephemeral + config.protocolClasses = [UnreachableStub.self] + config.httpAdditionalHeaders = ["X-Fail": header] + let down = Updater(currentVersion: "2.0.0", publicKey: r.publicKey, install: bin.install, configuration: config) + for op in ["check", "apply"] { + var thrown: Error? + do { + if op == "check" { _ = try await down.check(force: true) } else { _ = try await down.apply() } + } catch { thrown = error } + #expect(thrown is UpdateError, "\(op) with \(header): \(String(describing: thrown))") + } + } + #expect(bin.targetBytes == oldBytes) + } + + // MARK: AC-6, AC-7: signature and checksum + + @Test func rejectsABadSignature() async throws { + let bin = try Bin() + defer { bin.cleanup() } + var r = try CLIRelease(version: "2.0.1") + var bad = r.sig + bad[0] ^= 0xff + r.routes["\(dl)/v2.0.1/SHA256SUMS.sig"] = .body(200, bad) + let installer = StubInstaller() + let (u, id) = makeUpdater(r, bin: bin, current: "2.0.0", installer: installer) + await #expect(throws: UpdateError("SHA256SUMS signature is invalid: refusing to install.")) { try await u.apply() } + #expect(!UpdateStub.requests(id).contains(r.tarballURL), "the tarball is not downloaded before the signature verifies") + #expect(installer.calls.isEmpty) + #expect(bin.listing() == ["mlxr"], "nothing written next to the target: \(bin.listing())") + #expect(bin.targetBytes == oldBytes) + } + + @Test func rejectsASignatureByAnotherKey() async throws { + let bin = try Bin() + defer { bin.cleanup() } + let r = try CLIRelease(version: "2.0.1") + let other = try CLIRelease(version: "2.0.1") + var routes = r.routes + routes["\(dl)/v2.0.1/SHA256SUMS.sig"] = .body(200, other.sig) + let installer = StubInstaller() + let (u, _) = makeUpdater(r, bin: bin, current: "2.0.0", installer: installer, routes: routes) + await #expect(throws: UpdateError("SHA256SUMS signature is invalid: refusing to install.")) { try await u.apply() } + #expect(installer.calls.isEmpty) + #expect(bin.listing() == ["mlxr"]) + } + + @Test func rejectsAChecksumMismatch() async throws { + let bin = try Bin() + defer { bin.cleanup() } + var r = try CLIRelease(version: "2.0.1") + var tampered = r.tarball + tampered[tampered.count / 2] ^= 0x01 + r.routes[r.tarballURL] = .body(200, tampered) + let installer = StubInstaller() + let (u, _) = makeUpdater(r, bin: bin, current: "2.0.0", installer: installer) + var thrown: UpdateError? + do { _ = try await u.apply() } catch let e as UpdateError { thrown = e } catch {} + #expect(thrown?.message.hasPrefix("Checksum mismatch") == true, "got \(String(describing: thrown))") + #expect(installer.calls.isEmpty, "the installer is not invoked") + #expect(bin.listing() == ["mlxr"], "staging removed: \(bin.listing())") + #expect(bin.targetBytes == oldBytes) + } + + @Test func rejectsATarballMissingFromTheSignedList() async throws { + let bin = try Bin() + defer { bin.cleanup() } + var r = try CLIRelease(version: "2.0.1") + let text = Data("\(String(repeating: "0", count: 64)) mlxr-2.0.0-macos-arm64.tar.gz\n".utf8) + r.routes["\(dl)/v2.0.1/SHA256SUMS"] = .body(200, text) + r.routes["\(dl)/v2.0.1/SHA256SUMS.sig"] = .body(200, try r.key.signature(for: text)) + let installer = StubInstaller() + let (u, id) = makeUpdater(r, bin: bin, current: "2.0.0", installer: installer) + await #expect(throws: UpdateError("mlxr-2.0.1-macos-arm64.tar.gz is not in the signed checksum list.")) { try await u.apply() } + #expect(!UpdateStub.requests(id).contains(r.tarballURL)) + #expect(installer.calls.isEmpty) + #expect(bin.listing() == ["mlxr"]) + } + + // MARK: install failure cleanup + + @Test func aFailingInstallerLeavesNothingBehind() async throws { + let bin = try Bin() + defer { bin.cleanup() } + let r = try CLIRelease(version: "2.0.1") + let (u, _) = makeUpdater(r, bin: bin, current: "2.0.0", installer: FailingInstaller()) + await #expect(throws: UpdateError("install failed on purpose")) { try await u.apply() } + #expect(bin.listing() == ["mlxr"], "staging removed: \(bin.listing())") + #expect(bin.targetBytes == oldBytes) + // And the updater is usable again. + #expect(await u.isInstalling == false) + } + + // MARK: AC-9: source build + + @Test func sourceBuildIsRefusedBeforeDownloading() async throws { + let bin = try Bin() + defer { bin.cleanup() } + let build = bin.root.appendingPathComponent("repo/.build/release", isDirectory: true) + try FileManager.default.createDirectory(at: build, withIntermediateDirectories: true) + let exe = build.appendingPathComponent("mlxr") + try oldBytes.write(to: exe) + let install = UpdateInstall.detectCLI(executable: exe) + #expect(install.kind == .source) + let r = try CLIRelease(version: "2.0.1") + let installer = StubInstaller() + let (u, id) = makeUpdater(r, bin: bin, current: "2.0.0", install: install, installer: installer) + await #expect(throws: UpdateError("mlxr is running from a source build; update it with git pull")) { try await u.apply() } + #expect(UpdateStub.requests(id).allSatisfy { $0 == api }, "no release file requested: \(UpdateStub.requests(id))") + #expect(installer.calls.isEmpty) + #expect(try Data(contentsOf: exe) == oldBytes) + #expect(((try? FileManager.default.contentsOfDirectory(atPath: build.path)) ?? []) == ["mlxr"]) + } + + // MARK: AC-8: unwritable target + + @Test func unwritableTargetIsRefusedBeforeDownloading() async throws { + try #require(geteuid() != 0, "root can write anywhere") + let bin = try Bin() + defer { bin.cleanup() } + chmod(bin.dir.path, 0o555) + let r = try CLIRelease(version: "2.0.1") + let installer = StubInstaller() + let (u, id) = makeUpdater(r, bin: bin, current: "2.0.0", installer: installer) + let expected = UpdateError("cannot replace \(bin.target.path) (permission denied); run: sudo mlxr upgrade") + await #expect(throws: expected) { try await u.apply() } + #expect(UpdateStub.requests(id).allSatisfy { $0 == api }, + "no signature file or tarball requested before refusing: \(UpdateStub.requests(id))") + #expect(installer.calls.isEmpty) + #expect(bin.listing() == ["mlxr"]) + #expect(bin.targetBytes == oldBytes) + } +} From 4311b7c81e32ab5de79724fbb9e639734eae4330 Mon Sep 17 00:00:00 2001 From: Rolando Santamaria Maso Date: Sun, 8 Nov 2026 18:59:32 +0100 Subject: [PATCH 3/6] feat(cli): mlxr upgrade (alias update, --check) installs verified releases --- Sources/MLXRCLI/Commands.swift | 5 +- Sources/MLXRCLI/UpgradeCommand.swift | 46 ++ Tests/MLXRCLITests/UpgradeCommandTests.swift | 464 +++++++++++++++++++ 3 files changed, 513 insertions(+), 2 deletions(-) create mode 100644 Sources/MLXRCLI/UpgradeCommand.swift create mode 100644 Tests/MLXRCLITests/UpgradeCommandTests.swift diff --git a/Sources/MLXRCLI/Commands.swift b/Sources/MLXRCLI/Commands.swift index 9f3d036..a1bbbb9 100644 --- a/Sources/MLXRCLI/Commands.swift +++ b/Sources/MLXRCLI/Commands.swift @@ -13,7 +13,8 @@ extension CLI { catalog: Catalog = .standard, now: @escaping @Sendable () -> Date = { Date() }, hub: HubServices = .live, engine: GenerationEngine = LiveGenerationEngine(), interrupts: Interrupts = .shared, lineSource: LineSource? = nil, - chatHistory: ChatHistory = .live) -> [Command] { + chatHistory: ChatHistory = .live, + updater: @escaping @Sendable () -> Updater = { CLI.liveUpdater() }) -> [Command] { let runDeps = RunDependencies(resolver: ModelResolver(library: library, presets: presets, catalog: catalog), hub: hub, engine: engine, interrupts: interrupts, lineSource: lineSource, history: chatHistory) let ctxRange = SamplingLimits.context @@ -101,7 +102,7 @@ extension CLI { group: "Developer", run: { inv, console in try await services.bench(BenchOptions(model: inv.positionals[0], decodeOnly: inv.bool("decode"), contexts: inv.string("ctx")), console) }), - ] + modelCommands(library: library, presets: presets, catalog: catalog, now: now) + ] + modelCommands(library: library, presets: presets, catalog: catalog, now: now) + [upgradeCommand(updater: updater)] return table + [completionCommand(table: table)] } } diff --git a/Sources/MLXRCLI/UpgradeCommand.swift b/Sources/MLXRCLI/UpgradeCommand.swift new file mode 100644 index 0000000..44dcf48 --- /dev/null +++ b/Sources/MLXRCLI/UpgradeCommand.swift @@ -0,0 +1,46 @@ +import Foundation +import MLXEngine + +extension CLI { + /// The updater `mlxr upgrade` uses: the running binary, replaced in place by `CLIInstaller`. + public static func liveUpdater() -> Updater { + let exe = Bundle.main.executableURL ?? URL(fileURLWithPath: CommandLine.arguments[0]) + return Updater(install: .detectCLI(executable: exe), installer: CLIInstaller()) + } + + /// `upgrade` (alias `update`): installs the latest signed release over the running binary. + /// The updater is built lazily, so no other command ever reaches the update code. + static func upgradeCommand(updater: @escaping @Sendable () -> Updater) -> Command { + Command(name: "upgrade", aliases: ["update"], summary: "Update mlxr to the latest release", + options: [Opt(long: "check", help: "only report whether a newer release exists")], + run: { inv, console in try await executeUpgrade(inv, console, updater()) }) + } + + static func executeUpgrade(_ inv: Invocation, _ console: Console, _ updater: Updater) async throws { + // A source build is updated with git, whether or not a newer release exists. + if updater.install.kind == .source { + throw CLIError.failure("mlxr is running from a source build; update it with git pull") + } + let current = updater.currentVersion + let info = try await updater.check(force: true) + guard info.available, let latest = info.latest else { + console.out("mlxr is up to date (\(current))\n") + return + } + if inv.bool("check") { + console.out("mlxr \(latest) is available (you have \(current))\n") + return + } + let renderer = PullRenderer(console: console, label: "upgrading mlxr:") + defer { renderer.finish() } + let applied: AppliedUpdate + do { + applied = try await updater.apply(progress: { phase in + if console.stderrIsTTY, case .download(let f) = phase { + renderer.update(done: Int64(min(max(f, 0), 1) * 1000), total: 1000, speed: 0) + } + }) + } catch { renderer.finish(); throw error } + console.out("upgraded mlxr \(current) -> \(applied.version)\n") + } +} diff --git a/Tests/MLXRCLITests/UpgradeCommandTests.swift b/Tests/MLXRCLITests/UpgradeCommandTests.swift new file mode 100644 index 0000000..30931eb --- /dev/null +++ b/Tests/MLXRCLITests/UpgradeCommandTests.swift @@ -0,0 +1,464 @@ +import CryptoKit +import Foundation +import Testing +import MLXEngine +@testable import MLXRCLI + +// SL03: `mlxr upgrade` through the command table. No network: a URLProtocol stub serves the release +// API, SHA256SUMS, SHA256SUMS.sig and the tarball; a throwaway Ed25519 key stands in for UpdateKey; +// the installer is recorded, never run. + +private let api = "https://api.github.com/repos/BackendStack21/mlx-runner/releases/latest" +private let dl = "https://github.com/BackendStack21/mlx-runner/releases/download" +private let oldBytes = Data("old-binary".utf8) +private let barGlyph = "\u{2595}" // the left edge of the pull-style bar + +private func hex(_ d: Data) -> String { SHA256.hash(data: d).map { String(format: "%02x", $0) }.joined() } + +/// Serves canned responses to a URLSession, selected per test by the `X-Stub` header. +final class UpgradeStub: URLProtocol, @unchecked Sendable { + enum Route { + case body(Int, Data) + case fail(URLError.Code) + } + private static let lock = NSLock() + nonisolated(unsafe) private static var tables: [String: [String: Route]] = [:] + nonisolated(unsafe) private static var logs: [String: [String]] = [:] + + static func configuration(_ routes: [String: Route]) -> (URLSessionConfiguration, id: String) { + let id = UUID().uuidString + lock.withLock { tables[id] = routes } + let c = URLSessionConfiguration.ephemeral + c.protocolClasses = [UpgradeStub.self] + c.httpAdditionalHeaders = ["X-Stub": id] + return (c, id) + } + static func requests(_ id: String) -> [String] { lock.withLock { logs[id] ?? [] } } + + override class func canInit(with request: URLRequest) -> Bool { true } + override class func canonicalRequest(for request: URLRequest) -> URLRequest { request } + override func startLoading() { + let url = request.url! + let id = request.value(forHTTPHeaderField: "X-Stub") ?? "" + let route: Route? = Self.lock.withLock { + Self.logs[id, default: []].append(url.absoluteString) + return Self.tables[id]?[url.absoluteString] + } + switch route { + case .body(let status, let data)?: + let resp = HTTPURLResponse(url: url, statusCode: status, httpVersion: "HTTP/1.1", + headerFields: ["Content-Length": "\(data.count)"])! + client?.urlProtocol(self, didReceive: resp, cacheStoragePolicy: .notAllowed) + var i = 0 + while i < data.count { + let end = min(data.count, i + 4096) + client?.urlProtocol(self, didLoad: data.subdata(in: i.. [Command] { + let h = try! RunHarness() + let (config, id) = UpgradeStub.configuration(routes) + stubID = id + let target = bin.target + let installer = self.installer, factory = self.factory, release = self.release + let install = self.install ?? UpdateInstall(kind: .cli, target: target), current = self.current + return CLI.commands(services: FakeServices().services, library: h.library.library, presets: h.library.presets, + catalog: .standard, now: { LibraryFixture.now }, hub: h.hub.services, engine: h.engine, + interrupts: h.interrupts, + updater: { + factory.hit() + return Updater(currentVersion: current, publicKey: release.publicKey, install: install, + configuration: config, installer: installer) + }) + } + + func run(_ args: [String], stderrTTY: Bool = false, stdoutTTY: Bool = false) async -> (code: Int32, out: String, err: String) { + let cap = Capture() + let code = await CLI.run(args, console: cap.console(stdoutTTY: stdoutTTY, stderrTTY: stderrTTY), commands: table()) + return (code, cap.stdout, cap.stderr) + } +} + +@Suite("mlxr upgrade") +struct UpgradeCommandTests { + // MARK: version + + @Test func theVersionStaysAtTwoZeroZero() { + #expect(MLXRunnerVersion.current == "2.0.0") + } + + // MARK: AC-11 up to date + + @Test func upToDatePrintsOneLineAndExitsZero() async throws { + let rig = try UpgradeRig(latest: "2.0.0") + let r = await rig.run(["upgrade"]) + #expect(r.code == 0, "\(r.err)") + #expect(r.out == "mlxr is up to date (2.0.0)\n", "\(r.out)") + #expect(r.err.isEmpty, "\(r.err)") + #expect(!rig.tarballRequested && rig.installer.versions.isEmpty) + #expect(rig.bin.targetBytes == oldBytes) + } + + @Test func anOlderLatestReleaseCountsAsUpToDate() async throws { + let rig = try UpgradeRig(latest: "1.9.0") + let r = await rig.run(["upgrade"]) + #expect(r.code == 0 && r.out == "mlxr is up to date (2.0.0)\n", "\(r.out) \(r.err)") + #expect(rig.installer.versions.isEmpty) + } + + // MARK: AC-12 successful upgrade + + @Test func aSuccessfulUpgradePrintsTheTransitionOnStdout() async throws { + let rig = try UpgradeRig() + let r = await rig.run(["upgrade"]) + #expect(r.code == 0, "\(r.err)") + #expect(r.out == "upgraded mlxr 2.0.0 -> 2.0.1\n", "\(r.out)") + #expect(rig.installer.versions == ["2.0.1"]) + #expect(rig.requests.contains(rig.release.tarballURL)) + } + + @Test func noBarOrEscapesOnStderrWhenItIsNotATerminal() async throws { + let rig = try UpgradeRig() + let r = await rig.run(["upgrade"], stderrTTY: false) + #expect(r.code == 0, "\(r.err)") + #expect(!r.err.contains("\r") && !r.err.contains("\u{1B}") && !r.err.contains(barGlyph), "\(r.err.debugDescription)") + #expect(r.out == "upgraded mlxr 2.0.0 -> 2.0.1\n") + } + + @Test func theProgressBarGoesToStderrOnlyWhenItIsATerminal() async throws { + let rig = try UpgradeRig() + let r = await rig.run(["upgrade"], stderrTTY: true) + #expect(r.code == 0, "\(r.err)") + #expect(r.err.contains("\r") && r.err.contains(barGlyph), "\(r.err.debugDescription)") + #expect(r.out == "upgraded mlxr 2.0.0 -> 2.0.1\n", "progress never reaches stdout: \(r.out.debugDescription)") + } + + @Test func aTerminalStdoutDoesNotChangeTheResultLine() async throws { + let rig = try UpgradeRig() + let r = await rig.run(["upgrade"], stderrTTY: false, stdoutTTY: true) + #expect(r.out == "upgraded mlxr 2.0.0 -> 2.0.1\n", "\(r.out)") + } + + @Test func updateIsAnAliasForUpgrade() async throws { + let inv = try CLI.parse(["update"], commands: try UpgradeRig().table()) + #expect(inv.command.name == "upgrade") + let rig = try UpgradeRig() + let r = await rig.run(["update"]) + #expect(r.code == 0 && r.out == "upgraded mlxr 2.0.0 -> 2.0.1\n", "\(r.out) \(r.err)") + let up = try UpgradeRig(latest: "2.0.0") + let r2 = await up.run(["update", "--check"]) + #expect(r2.code == 0 && r2.out == "mlxr is up to date (2.0.0)\n", "\(r2.out) \(r2.err)") + } + + // MARK: AC-13 --check + + @Test func checkReportsANewerReleaseWithoutInstalling() async throws { + let rig = try UpgradeRig() + let r = await rig.run(["upgrade", "--check"]) + #expect(r.code == 0, "\(r.err)") + #expect(r.out == "mlxr 2.0.1 is available (you have 2.0.0)\n", "\(r.out)") + #expect(r.err.isEmpty, "\(r.err)") + #expect(rig.installer.versions.isEmpty) + #expect(!rig.tarballRequested) + #expect(rig.requests.allSatisfy { $0 == api }, "only the release API is asked: \(rig.requests)") + #expect(rig.bin.targetBytes == oldBytes) + } + + @Test func checkWhenUpToDatePrintsTheUpToDateLine() async throws { + let rig = try UpgradeRig(latest: "2.0.0") + let r = await rig.run(["upgrade", "--check"]) + #expect(r.code == 0 && r.out == "mlxr is up to date (2.0.0)\n", "\(r.out) \(r.err)") + #expect(rig.installer.versions.isEmpty) + } + + @Test func checkFailuresAreErrors() async throws { + let rig = try UpgradeRig(routes: [api: .body(503, Data())]) + let r = await rig.run(["upgrade", "--check"]) + #expect(r.code == 1) + #expect(r.out.isEmpty) + #expect(r.err == "Error: Update check failed: GitHub answered 503.\n", "\(r.err)") + } + + // MARK: AC-14 failures + + @Test func aBadSignatureIsRefusedAndNothingIsWritten() async throws { + let rig = try UpgradeRig(tamper: .signature) + let r = await rig.run(["upgrade"]) + #expect(r.code == 1) + #expect(r.out.isEmpty, "\(r.out)") + #expect(r.err == "Error: SHA256SUMS signature is invalid: refusing to install.\n", "\(r.err)") + #expect(rig.installer.versions.isEmpty && !rig.tarballRequested) + #expect(rig.bin.targetBytes == oldBytes) + #expect(rig.bin.listing == ["mlxr"], "\(rig.bin.listing)") + } + + @Test func aChecksumMismatchIsRefused() async throws { + let rig = try UpgradeRig(tamper: .digest) + let r = await rig.run(["upgrade"]) + #expect(r.code == 1) + #expect(r.out.isEmpty, "\(r.out)") + #expect(r.err.hasPrefix("Error: Checksum mismatch for \(rig.release.assetName)"), "\(r.err)") + #expect(r.err.hasSuffix("\n") && r.err.filter { $0 == "\n" }.count == 1, "one line: \(r.err.debugDescription)") + #expect(rig.installer.versions.isEmpty) + #expect(rig.bin.targetBytes == oldBytes && rig.bin.listing == ["mlxr"]) + } + + @Test(.enabled(if: geteuid() != 0, "root can write anywhere")) + func anUnwritableDirectoryNamesSudo() async throws { + let rig = try UpgradeRig() + chmod(rig.bin.dir.path, 0o555) + let r = await rig.run(["upgrade"]) + #expect(r.code == 1) + #expect(r.out.isEmpty, "\(r.out)") + #expect(r.err == "Error: cannot replace \(rig.bin.target.path) (permission denied); run: sudo mlxr upgrade\n", "\(r.err)") + #expect(!rig.tarballRequested && rig.installer.versions.isEmpty) + #expect(rig.bin.targetBytes == oldBytes) + } + + @Test func aSourceBuildIsRefusedWithAGitHint() async throws { + let source = UpdateInstall.detectCLI(executable: URL(fileURLWithPath: "/work/mlx-runner/.build/debug/mlxr")) + #expect(source.kind == .source) + let rig = try UpgradeRig(install: source) + let r = await rig.run(["upgrade"]) + #expect(r.code == 1) + #expect(r.out.isEmpty, "\(r.out)") + #expect(r.err == "Error: mlxr is running from a source build; update it with git pull\n", "\(r.err)") + #expect(!rig.tarballRequested && rig.installer.versions.isEmpty) + } + + @Test(arguments: ["2.0.0", "1.9.0"]) + func aSourceBuildIsRefusedEvenWhenNoNewerReleaseExists(latest: String) async throws { + let source = UpdateInstall.detectCLI(executable: URL(fileURLWithPath: "/work/mlx-runner/.build/release/mlxr")) + let rig = try UpgradeRig(latest: latest, install: source) + let r = await rig.run(["upgrade"]) + #expect(r.code == 1, "\(r.out)") + #expect(r.out.isEmpty, "\(r.out)") + #expect(r.err == "Error: mlxr is running from a source build; update it with git pull\n", "\(r.err)") + #expect(rig.installer.versions.isEmpty && !rig.tarballRequested) + } + + @Test func aSourceBuildIsRefusedForUpdateToo() async throws { + let source = UpdateInstall.detectCLI(executable: URL(fileURLWithPath: "/work/mlx-runner/.build/debug/mlxr")) + let rig = try UpgradeRig(latest: "2.0.0", install: source) + let r = await rig.run(["update"]) + #expect(r.code == 1 && r.err == "Error: mlxr is running from a source build; update it with git pull\n", "\(r.err)") + } + + @Test func aServerErrorOnTheReleaseCheckIsAnError() async throws { + let rig = try UpgradeRig(routes: [api: .body(500, Data())]) + let r = await rig.run(["upgrade"]) + #expect(r.code == 1 && r.out.isEmpty) + #expect(r.err == "Error: Update check failed: GitHub answered 500.\n", "\(r.err)") + #expect(rig.bin.targetBytes == oldBytes) + } + + @Test func aServerErrorOnTheDownloadIsAnError() async throws { + let broken = try UpgradeRig(failTarball: 500) + let r = await broken.run(["upgrade"]) + #expect(r.code == 1 && r.out.isEmpty) + #expect(r.err.hasPrefix("Error: "), "\(r.err)") + #expect(broken.installer.versions.isEmpty) + #expect(broken.bin.targetBytes == oldBytes && broken.bin.listing == ["mlxr"]) + } + + @Test(arguments: [URLError.Code.cannotFindHost, .timedOut, .notConnectedToInternet]) + func anUnreachableHostIsAnError(code: URLError.Code) async throws { + let rig = try UpgradeRig(routes: [api: .fail(code)]) + let r = await rig.run(["upgrade"]) + #expect(r.code == 1 && r.out.isEmpty) + #expect(r.err.hasPrefix("Error: ") && r.err.hasSuffix("\n"), "\(r.err.debugDescription)") + #expect(r.err.filter { $0 == "\n" }.count == 1, "\(r.err.debugDescription)") + #expect(rig.bin.targetBytes == oldBytes) + } + + // MARK: AC-15 table, help, completions, parser + + @Test func theTableResolvesBothNames() throws { + let table = CLI.commands + #expect(try CLI.parse(["upgrade"], commands: table).command.name == "upgrade") + #expect(try CLI.parse(["update"], commands: table).command.name == "upgrade") + #expect(try CLI.parse(["upgrade", "--check"], commands: table).bool("check")) + #expect(!(try CLI.parse(["upgrade"], commands: table).bool("check"))) + } + + @Test func commandHelpListsTheFlagAndTheAlias() async { + for name in ["upgrade", "update"] { + let cap = Capture() + #expect(await CLI.run([name, "--help"], console: cap.console()) == 0) + #expect(cap.stdout.contains("Usage:\n mlxr upgrade"), "\(cap.stdout)") + #expect(cap.stdout.contains("Aliases:\n upgrade, update"), "\(cap.stdout)") + #expect(cap.stdout.contains("--check"), "\(cap.stdout)") + } + let cap = Capture() + #expect(await CLI.run(["help", "update"], console: cap.console()) == 0) + #expect(cap.stdout.contains("Usage:\n mlxr upgrade"), "\(cap.stdout)") + } + + @Test func rootHelpListsUpgrade() async { + let cap = Capture() + #expect(await CLI.run(["--help"], console: cap.console()) == 0) + let lines = cap.stdout.split(separator: "\n").map { $0.trimmingCharacters(in: .whitespaces) } + #expect(lines.contains { $0.hasPrefix("upgrade ") }, "\(cap.stdout)") + } + + @Test func helpNeverRunsTheUpdater() async throws { + let rig = try UpgradeRig() + let r = await rig.run(["upgrade", "--help"]) + #expect(r.code == 0 && r.out.contains("--check")) + #expect(rig.factory.count == 0 && rig.requests.isEmpty && rig.installer.versions.isEmpty) + } + + @Test(arguments: ["zsh", "bash"]) + func completionsOfferTheCommandAndItsFlag(shell: String) async { + let cap = Capture() + #expect(await CLI.run(["completion", shell], console: cap.console()) == 0) + #expect(cap.stdout.contains("upgrade") && cap.stdout.contains("update"), "\(shell)") + #expect(cap.stdout.contains("--check"), "\(shell)") + } + + @Test(arguments: [["upgrade", "--bogus"], ["upgrade", "--check=maybe"], ["upgrade", "now"], ["upgrade", "-x"]]) + func unknownFlagsAndArgumentsAreRejectedBeforeAnythingRuns(argv: [String]) async throws { + let rig = try UpgradeRig() + let r = await rig.run(argv) + #expect(r.code == 1, "\(argv)") + #expect(r.out.isEmpty, "\(r.out)") + #expect(r.err.hasPrefix("Error: "), "\(r.err)") + #expect(rig.factory.count == 0 && rig.requests.isEmpty && rig.installer.versions.isEmpty) + } + + // MARK: no other command updates (plan review R-02) + + @Test func buildingTheTableDoesNotCreateAnUpdater() throws { + let rig = try UpgradeRig() + _ = rig.table() + #expect(rig.factory.count == 0) + } + + @Test func noOtherCommandTouchesTheUpdaterOrTheNetwork() async throws { + let rig = try UpgradeRig() + let argvs: [[String]] = [ + ["run", "qwen3:0.6b", "hi"], ["list"], ["ls"], ["show", "qwen3:0.6b"], ["show", "nope/none"], + ["pull", "mlx-community/Qwen3-0.6B-4bit"], ["rm", "nope/none"], ["search", "qwen"], + ["tokenize", "qwen3:0.6b", "hi"], ["--version"], ["version"], ["help"], ["--help"], + ["completion", "zsh"], ["run", "--help"], ["bogus"], + ] + for argv in argvs { + _ = await rig.run(argv) + #expect(rig.factory.count == 0, "\(argv) built an updater") + #expect(rig.requests.isEmpty, "\(argv) made an update request: \(rig.requests)") + #expect(rig.installer.versions.isEmpty, "\(argv)") + } + #expect(rig.bin.targetBytes == oldBytes) + } +} From 6425fa7079e66b0377b20b57acdd1897985cf2cc Mon Sep 17 00:00:00 2001 From: Rolando Santamaria Maso Date: Sun, 8 Nov 2026 19:27:57 +0100 Subject: [PATCH 4/6] docs(cli): mlxr upgrade in README, landing page and CHANGELOG 2.0.0 --- CHANGELOG.md | 1 + README.md | 3 +- Tests/MLXRCLITests/UpgradeDocsTests.swift | 88 +++++++++++++++++++++++ site/index.html | 2 +- 4 files changed, 92 insertions(+), 2 deletions(-) create mode 100644 Tests/MLXRCLITests/UpgradeDocsTests.swift diff --git a/CHANGELOG.md b/CHANGELOG.md index 661c883..dde9c20 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,7 @@ The command line now follows Ollama: the same verbs, flags, help layout and erro - **`run` flags:** `--verbose`, `--think[=true|false|high|medium|low]`, `--hidethinking`, `--nowordwrap`, `--keepalive` and `--insecure` (accepted, no effect), `--system`, `--temp` (alias `--temperature`), `--top-p`, `--top-k`, `--min-p`, `--repeat-penalty`, `--repeat-last-n`, `--seed`, `-n` / `--max-tokens` (`--max` still works), `--ctx`, `--raw`, `--draft`, `--sparse`, `--spec`, `--ids`, `--no-think`. Options are validated strictly with ranges. Presence and frequency penalty, `--format` and the other options the engine doesn't implement are refused with a clear error. - **Thinking display as in Ollama:** `Thinking...`, the reasoning, `...done thinking.` and a blank line (dim on a terminal); `--hidethinking` drops it. Word wrap on a terminal, off with `--nowordwrap` or when stdout is not a terminal. - **Interactive chat** with Ollama's slash commands, `>>> ` and `... ` prompts, multiline input, and line editing and history through the system libedit (no package). A cancelled reply keeps your turn; changing `num_ctx` reloads the model; the history sent to the model is capped. +- **`mlxr upgrade`** (alias `update`) replaces the CLI in place with the latest release, after checking the signed `SHA256SUMS`, the archive digest and the binary's code signature; `--check` only reports. Use `sudo mlxr upgrade` when it is installed in `/usr/local/bin`. 1.x has no such command: reinstall once to get it. - **Shell completions:** `mlxr completion zsh` and `bash`, generated from the command tables. **Deliberate differences from Ollama** diff --git a/README.md b/README.md index 1c7451b..c3a2b76 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ sudo mkdir -p /usr/local/bin sudo install -m 755 mlxr--macos-arm64/mlxr /usr/local/bin/mlxr ``` -A browser download is quarantined by macOS and the binary won't start until you run `xattr -d com.apple.quarantine /usr/local/bin/mlxr`. The CLI doesn't update itself: repeat the steps for a new version. +A browser download is quarantined by macOS and the binary won't start until you run `xattr -d com.apple.quarantine /usr/local/bin/mlxr`. From 2.0 on the CLI updates itself: run `mlxr upgrade` (`sudo mlxr upgrade` when it is installed in `/usr/local/bin`). 1.x has no upgrade command, so repeat these steps once to move to 2.0. ### Verifying a download @@ -194,6 +194,7 @@ mlxr rm mlx-community/Qwen3-4B-4bit # remove a model; `cp` copies, `ps` mlxr serve mlx-community/Qwen3-4B-4bit --port 1234 # OpenAI-compatible server (--lan prints an API key) mlxr run mlx-community/Qwen3-8B-4bit --draft mlx-community/Qwen3-0.6B-4bit # speculative decoding (or --draft auto) mlxr completion zsh # shell completions (zsh, bash) +mlxr upgrade # update mlxr in place, verified against the signed SHA256SUMS (alias: update; --check only looks; `sudo mlxr upgrade` when installed in /usr/local/bin) ``` Reproducible output (greedy): `mlxr run "Explain RoPE" --temp 0 --repeat-penalty 1 --seed 42 --max 256`. Use these diff --git a/Tests/MLXRCLITests/UpgradeDocsTests.swift b/Tests/MLXRCLITests/UpgradeDocsTests.swift new file mode 100644 index 0000000..59e0ceb --- /dev/null +++ b/Tests/MLXRCLITests/UpgradeDocsTests.swift @@ -0,0 +1,88 @@ +import Foundation +import Testing +@testable import MLXRCLI + +/// SL04 (AC-16): the docs describe `mlxr upgrade`, and stay true for 1.x users who do not have it. +@Suite("mlxr upgrade documentation (SL04)") +struct UpgradeDocsTests { + static func read(_ path: String) -> String { ReleaseDocsTests.read(path) } + + /// Text between `start` and the next line starting with `endPrefix` (exclusive). + static func section(_ text: String, from start: String, until endPrefix: String) -> String { + let lines = text.components(separatedBy: "\n") + guard let i = lines.firstIndex(where: { $0.hasPrefix(start) }) else { return "" } + return lines[(i + 1)...].prefix { !$0.hasPrefix(endPrefix) }.joined(separator: "\n") + } + + @Test func readmeCliSectionDescribesUpgrade() { + let body = Self.section(Self.read("README.md"), from: "## Command line (`mlxr`)", until: "## ") + #expect(!body.isEmpty, "README has no Command line section") + #expect(body.contains("mlxr upgrade"), "CLI section does not mention `mlxr upgrade`") + #expect(body.contains("sudo mlxr upgrade"), "CLI section does not mention `sudo mlxr upgrade` for /usr/local/bin") + #expect(body.contains("/usr/local/bin"), "CLI section does not say when sudo is needed") + } + + @Test func readmeCliOnlyInstallStepsDescribeUpgrade() { + let readme = Self.read("README.md") + let body = Self.section(readme, from: "The CLI on its own", until: "### ") + #expect(!body.isEmpty, "README has no CLI-only install steps") + #expect(body.contains("mlxr upgrade"), "install steps do not mention `mlxr upgrade`") + #expect(body.contains("sudo mlxr upgrade"), "install steps do not mention `sudo mlxr upgrade`") + #expect(!body.contains("The CLI doesn't update itself"), "stale claim that the CLI never updates itself") + } + + @Test func readmeSaysOneDotXHasNoUpgradeCommand() { + let body = Self.section(Self.read("README.md"), from: "The CLI on its own", until: "### ") + #expect(body.contains("1.x"), "install steps do not say how 1.x users move to 2.0") + } + + @Test func siteCliInstallNoteMentionsUpgradeAndStaysTrueFor1x() { + let html = Self.read("site/index.html") + guard let r = html.range(of: "id=\"cli-install\"") else { + Issue.record("no #cli-install"); return + } + let rest = html[r.upperBound...] + let end = rest.range(of: "")?.lowerBound ?? rest.endIndex + let block = String(rest[..= 2, "only \(seen) lines mention `mlxr upgrade` in README and site") + let sample = DocsCommands.check("```\nmlxr upgrade\nsudo mlxr upgrade --check\nmlxr update\n```", + file: "u.md", html: false, commands: table) + #expect(sample.checked >= 2 && sample.failures.isEmpty, "\(sample.failures)") + } +} diff --git a/site/index.html b/site/index.html index 6f1b758..ff79c4c 100644 --- a/site/index.html +++ b/site/index.html @@ -441,7 +441,7 @@

Only the CLI

sudo mkdir -p /usr/local/bin sudo install -m 755 mlxr-<version>-macos-arm64/mlxr /usr/local/bin/mlxr mlxr # prints help"> -

Use curl as shown: macOS quarantines an archive downloaded in a browser, and the binary won't start until you run xattr -d com.apple.quarantine /usr/local/bin/mlxr. It uses the same model library as the app. To update, run the commands again (the CLI doesn't update itself). To check the archive first, see Verify.

+

Use curl as shown: macOS quarantines an archive downloaded in a browser, and the binary won't start until you run xattr -d com.apple.quarantine /usr/local/bin/mlxr. It uses the same model library as the app. To update, run mlxr upgrade (sudo mlxr upgrade when it is in /usr/local/bin); it checks the signature before it replaces anything. 1.x has no upgrade command, so run the commands above once to get 2.0. To check the archive first, see Verify.

From 621ab3a2b2035551c4066f2da3728883c2417b44 Mon Sep 17 00:00:00 2001 From: Rolando Santamaria Maso Date: Sun, 8 Nov 2026 19:41:25 +0100 Subject: [PATCH 5/6] fix(cli): upgrade progress shows only known values; one release request per upgrade --- Sources/MLXEngine/Updater.swift | 5 +- Sources/MLXRCLI/UpgradeCommand.swift | 46 +++++++++--- Tests/MLXRCLITests/UpgradePolishTests.swift | 81 +++++++++++++++++++++ 3 files changed, 120 insertions(+), 12 deletions(-) create mode 100644 Tests/MLXRCLITests/UpgradePolishTests.swift diff --git a/Sources/MLXEngine/Updater.swift b/Sources/MLXEngine/Updater.swift index 6ae84ec..2b40ca3 100644 --- a/Sources/MLXEngine/Updater.swift +++ b/Sources/MLXEngine/Updater.swift @@ -349,13 +349,14 @@ public actor Updater { /// Downloads, verifies and installs the latest release, reporting each phase. Returns the /// installed version; the caller restarts the app (`Updater.relaunch`). - public func apply(progress: @escaping @Sendable (UpdatePhase) -> Void = { _ in }) async throws -> AppliedUpdate { + /// - Parameter reuseCheck: use the release found by a recent `check()` instead of asking GitHub again. + public func apply(reuseCheck: Bool = false, progress: @escaping @Sendable (UpdatePhase) -> Void = { _ in }) async throws -> AppliedUpdate { guard !busy else { throw UpdateError("An update is already being installed.") } busy = true defer { busy = false } progress(.checking) - let info = try await check(force: true) + let info = try await check(force: !reuseCheck) guard info.available, let release = cached?.release else { throw UpdateError(install.isCommandLine ? "mlxr is already up to date." : "MLX Runner is already up to date.") } guard info.canInstall else { throw UpdateError(info.reason ?? "This update can't be installed automatically.") } let name = UpdateInstall.assetName(for: release.version, kind: install.kind) diff --git a/Sources/MLXRCLI/UpgradeCommand.swift b/Sources/MLXRCLI/UpgradeCommand.swift index 44dcf48..a81b285 100644 --- a/Sources/MLXRCLI/UpgradeCommand.swift +++ b/Sources/MLXRCLI/UpgradeCommand.swift @@ -31,16 +31,42 @@ extension CLI { console.out("mlxr \(latest) is available (you have \(current))\n") return } - let renderer = PullRenderer(console: console, label: "upgrading mlxr:") - defer { renderer.finish() } - let applied: AppliedUpdate - do { - applied = try await updater.apply(progress: { phase in - if console.stderrIsTTY, case .download(let f) = phase { - renderer.update(done: Int64(min(max(f, 0), 1) * 1000), total: 1000, speed: 0) - } - }) - } catch { renderer.finish(); throw error } + // The updater reports a percentage only, so the bar shows no sizes or speed. + let bar = UpgradeBar(console: console) + defer { bar.finish() } + let applied = try await updater.apply(reuseCheck: true, progress: { phase in + if case .download(let f) = phase { bar.update(f) } + }) console.out("upgraded mlxr \(current) -> \(applied.version)\n") } } + +/// A percentage-only progress bar on stderr, drawn only when stderr is a terminal. +final class UpgradeBar: @unchecked Sendable { + private let console: Console + private let lock = NSLock() + private var drawn = false + + init(console: Console) { self.console = console } + + static func line(_ fraction: Double, width: Int = 10) -> String { + let f = fraction.isFinite ? min(max(fraction, 0), 1) : 0 + let filled = Int(Double(width) * f) + return "upgrading mlxr: " + String(format: "%3.0f%%", f * 100) + " \u{2595}" + + String(repeating: "\u{2588}", count: filled) + String(repeating: " ", count: width - filled) + "\u{258F}" + } + + func update(_ fraction: Double) { + guard console.stderrIsTTY else { return } + lock.withLock { + console.err("\r" + Self.line(fraction) + "\u{1B}[K") + drawn = true + } + } + + func finish() { + lock.withLock { + if drawn { console.err("\n"); drawn = false } + } + } +} diff --git a/Tests/MLXRCLITests/UpgradePolishTests.swift b/Tests/MLXRCLITests/UpgradePolishTests.swift new file mode 100644 index 0000000..6937585 --- /dev/null +++ b/Tests/MLXRCLITests/UpgradePolishTests.swift @@ -0,0 +1,81 @@ +import CryptoKit +import Foundation +import Testing +import MLXEngine +@testable import MLXRCLI + +// Final-review polish for `mlxr upgrade`: no invented byte counts on the progress line, and one +// release-API request per upgrade. + +private let api = "https://api.github.com/repos/BackendStack21/mlx-runner/releases/latest" +private let dl = "https://github.com/BackendStack21/mlx-runner/releases/download" + +private struct PolishFixture { + let key = Curve25519.Signing.PrivateKey() + let routes: [String: UpgradeStub.Route] + let config: URLSessionConfiguration + let id: String + let dir: URL + let target: URL + + init() throws { + let tarball = Data((0..<20_000).map { UInt8($0 % 251) }) + let name = UpdateInstall.assetName(for: "2.0.1", kind: .cli) + let digest = SHA256.hash(data: tarball).map { String(format: "%02x", $0) }.joined() + let sums = Data("\(digest) \(name)\n".utf8) + let sig = try key.signature(for: sums) + let json: [String: Any] = [ + "tag_name": "v2.0.1", "html_url": "https://github.com/BackendStack21/mlx-runner/releases/tag/v2.0.1", + "body": "notes", "draft": false, "prerelease": false, + "assets": [name, "SHA256SUMS", "SHA256SUMS.sig"].map { ["name": $0, "browser_download_url": "\(dl)/v2.0.1/\($0)"] }, + ] + routes = [ + api: .body(200, try JSONSerialization.data(withJSONObject: json)), + "\(dl)/v2.0.1/\(name)": .body(200, tarball), + "\(dl)/v2.0.1/SHA256SUMS": .body(200, sums), + "\(dl)/v2.0.1/SHA256SUMS.sig": .body(200, sig), + ] + (config, id) = UpgradeStub.configuration(routes) + dir = FileManager.default.temporaryDirectory.appendingPathComponent("mlxr-polish-\(UUID().uuidString)", isDirectory: true) + target = dir.appendingPathComponent("mlxr") + try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true) + try Data("old".utf8).write(to: target) + } + + func run(stderrTTY: Bool) async throws -> (code: Int32, out: String, err: String) { + defer { try? FileManager.default.removeItem(at: dir) } + let h = try RunHarness() + let updater = Updater(currentVersion: "2.0.0", publicKey: key.publicKey.rawRepresentation.base64EncodedString(), + install: UpdateInstall(kind: .cli, target: target), configuration: config, + installer: RecordingInstaller()) + let table = CLI.commands(services: FakeServices().services, library: h.library.library, presets: h.library.presets, + catalog: .standard, now: { LibraryFixture.now }, hub: h.hub.services, engine: h.engine, + interrupts: h.interrupts, updater: { updater }) + let cap = Capture() + let code = await CLI.run(["upgrade"], console: cap.console(stderrTTY: stderrTTY), commands: table) + return (code, cap.stdout, cap.stderr) + } +} + +@Suite("mlxr upgrade polish") +struct UpgradePolishTests { + @Test func theTerminalBarShowsNoMadeUpByteCountsOrSpeed() async throws { + let f = try PolishFixture() + let r = try await f.run(stderrTTY: true) + #expect(r.code == 0, "\(r.err)") + #expect(r.err.contains("\u{2595}"), "a bar is still drawn: \(r.err.debugDescription)") + #expect(r.err.contains("100%"), "\(r.err.debugDescription)") + #expect(!r.err.contains("/s"), "no speed field: \(r.err.debugDescription)") + for fake in ["1000 B", "1.0 kB", "1.0 KB", "1000/1000", "0 B"] { + #expect(!r.err.contains(fake), "\(fake) was never downloaded: \(r.err.debugDescription)") + } + } + + @Test func aSuccessfulUpgradeAsksTheReleaseAPIExactlyOnce() async throws { + let f = try PolishFixture() + let r = try await f.run(stderrTTY: false) + #expect(r.code == 0 && r.out == "upgraded mlxr 2.0.0 -> 2.0.1\n", "\(r.out) \(r.err)") + let hits = UpgradeStub.requests(f.id).filter { $0 == api }.count + #expect(hits == 1, "release API requests: \(UpgradeStub.requests(f.id))") + } +} From 8656065e4f76c53f6a11c6d66cd7e5a44f69cf84 Mon Sep 17 00:00:00 2001 From: Rolando Santamaria Maso Date: Sun, 8 Nov 2026 20:38:31 +0100 Subject: [PATCH 6/6] fix(cli): serve never echoes a supplied API key `mlxr serve` printed its API key on every start, including a key the user passed with --api-key or MLXR_API_KEY (CodeQL: cleartext logging). A supplied key is no longer printed; a key that --lan generates is still shown once, because the operator has no other way to learn it. Co-Authored-By: Claude Opus 5.5 --- Sources/MLXRCLI/Legacy.swift | 13 +++++++++++-- Tests/MLXRCLITests/ServeKeyNoticeTests.swift | 20 ++++++++++++++++++++ 2 files changed, 31 insertions(+), 2 deletions(-) create mode 100644 Tests/MLXRCLITests/ServeKeyNoticeTests.swift diff --git a/Sources/MLXRCLI/Legacy.swift b/Sources/MLXRCLI/Legacy.swift index e0af795..c4c6938 100644 --- a/Sources/MLXRCLI/Legacy.swift +++ b/Sources/MLXRCLI/Legacy.swift @@ -400,11 +400,20 @@ func legacyBench(_ model: String) throws { if !longBench.contexts.isEmpty { try benchLongContext(t, dir: dir, bench: longBench) } } +/// What `serve` prints about its API key. A key `--lan` generated is shown once, because the operator has +/// no other way to learn it; a key the user supplied (`--api-key`, `MLXR_API_KEY`) is never echoed. +func serveKeyNotice(key: String?, generated: Bool) -> String? { + guard let key else { return nil } + return generated ? "API key (send as 'Authorization: Bearer '): \(key)" + : "API key required: send it as 'Authorization: Bearer '" +} + func legacyServe(model: String, port: UInt16, ctx: Int, lan: Bool, apiKey: String?, draft: String?, sparse: String?) async throws { let sparseArg = try sparseSetting(sparse) // LAN mode always needs a key: use --api-key / MLXR_API_KEY, or generate one. var key = apiKey ?? ProcessInfo.processInfo.environment["MLXR_API_KEY"] - if lan && key == nil { key = OpenAIServer.generateAPIKey() } + let generated = lan && key == nil + if generated { key = OpenAIServer.generateAPIKey() } let dir = try installedModelDirectory(model, resolver: .live) let info = try await InferenceEngine.shared.load(directory: dir, draftDirectory: try draftDirectory(draft, target: dir), contextLength: ctx, sparse: sparseArg) print("Loaded \(info.name)\(info.draftName.map { " + draft \($0)" } ?? "") in \(String(format: "%.2f", info.loadSeconds))s") @@ -413,6 +422,6 @@ func legacyServe(model: String, port: UInt16, ctx: Int, lan: Bool, apiKey: Strin server.onLog = { print($0) } try startServer { try server.start() } print("OpenAI-compatible server on http://\(lan ? "0.0.0.0" : "127.0.0.1"):\(port)/v1 (Ctrl-C to stop)") - if let key { print("API key (send as 'Authorization: Bearer '): \(key)") } + if let notice = serveKeyNotice(key: key, generated: generated) { print(notice) } while true { try await Task.sleep(nanoseconds: 3_600_000_000_000) } } diff --git a/Tests/MLXRCLITests/ServeKeyNoticeTests.swift b/Tests/MLXRCLITests/ServeKeyNoticeTests.swift new file mode 100644 index 0000000..23bd7b4 --- /dev/null +++ b/Tests/MLXRCLITests/ServeKeyNoticeTests.swift @@ -0,0 +1,20 @@ +import Testing +@testable import MLXRCLI + +@Suite("serve shows only a key it generated") +struct ServeKeyNoticeTests { + @Test func generatedKeyIsShownOnce() { + let line = serveKeyNotice(key: "mlxr-generated-123", generated: true) + #expect(line == "API key (send as 'Authorization: Bearer '): mlxr-generated-123") + } + + @Test func suppliedKeyIsNeverEchoed() throws { + let line = try #require(serveKeyNotice(key: "my-own-secret", generated: false)) + #expect(!line.contains("my-own-secret")) + #expect(line == "API key required: send it as 'Authorization: Bearer '") + } + + @Test func noKeyNoNotice() { + #expect(serveKeyNotice(key: nil, generated: false) == nil) + } +}