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/Sources/MLXEngine/Updater.swift b/Sources/MLXEngine/Updater.swift index d014034..2b40ca3 100644 --- a/Sources/MLXEngine/Updater.swift +++ b/Sources/MLXEngine/Updater.swift @@ -50,15 +50,20 @@ 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 /// 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. @@ -67,10 +72,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, isCommandLine: true) + } + + /// 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`. @@ -300,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." } @@ -322,16 +349,17 @@ 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) - guard info.available, let release = cached?.release else { throw UpdateError("MLX Runner is already up to date.") } + 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) + 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.") } @@ -460,13 +488,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)") } } } @@ -669,3 +701,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/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/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/Sources/MLXRCLI/UpgradeCommand.swift b/Sources/MLXRCLI/UpgradeCommand.swift new file mode 100644 index 0000000..a81b285 --- /dev/null +++ b/Sources/MLXRCLI/UpgradeCommand.swift @@ -0,0 +1,72 @@ +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 + } + // 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/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) + } +} 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() + } +} 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) + } +} 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) + } +} 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/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))") + } +} 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.