Adopt SwiftLint

.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*.swift]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true

.github/workflows/swiftlint.yml

@@ -0,0 +1,18 @@
+---
+name: SwiftLint
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/swiftlint.yml'
+      - '.swiftlint.yml'
+      - '**/*.swift'
+  push:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v6
+      - run: brew install swiftlint
+      - run: swiftlint lint --strict

.swiftlint.yml

@@ -0,0 +1,36 @@
+included:
+  - Sources
+  - Tests
+  - Demos
+
+excluded:
+  - .build
+  - .swiftpm
+  - "**/.build"
+  - "**/.swiftpm"
+  - Sources/SwiftMail/SwiftMail.docc
+
+# 4-space indentation is enforced by `.editorconfig` (read by Xcode and most
+# editors) and by running `swiftformat --indent 4` locally before committing.
+# SwiftLint's `indentation_width` rule is not enabled — it rejects the standard
+# multi-line condition continuation style (alignment with first condition past
+# `if `/`guard `), which is widely used and not worth reformatting away.
+
+# Match Xcode's default "Indent switch statement `case` labels in" setting —
+# cases are indented one level past the `switch` keyword, body two levels.
+switch_case_alignment:
+  indented_cases: true
+
+identifier_name:
+  # Domain-specific names allowed because renaming would either break public
+  # API or lose protocol-level meaning:
+  #   - `to` / `cc`: RFC 5322 header field names on Message / MessageInfo / SearchCriteria
+  #   - `os`: RFC 2971 IMAP ID parameter name on Identification
+  #   - `on` / `or`: RFC 3501 IMAP SEARCH keyword enum cases on SearchCriteria
+  excluded:
+    - id
+    - to
+    - cc
+    - os
+    - on
+    - or

Demos/SwiftIMAPCLI/Commands/DownloadAttachment.swift

@@ -0,0 +1,105 @@
+import Foundation
+import ArgumentParser
+import SwiftMail
+
+struct DownloadAttachment: ParsableCommand {
+    static let configuration = CommandConfiguration(
+        commandName: "attachment",
+        abstract: "Download attachments for a message UID"
+    )
+
+    @Argument(help: "UID(s) of the message (comma-separated; ranges like 1-3 allowed)")
+    var uid: String
+
+    @Option(name: .shortAndLong, help: "Mailbox")
+    var mailbox: String = "INBOX"
+
+    @Option(help: "Attachment file extension to match (repeatable, e.g. pdf, docx)")
+    var attachment: [String] = []
+
+    @Option(help: "Output directory")
+    var out: String = "."
+
+    private func attachmentExtensions() -> Set<String> {
+        Set(
+            attachment
+                .map { $0.lowercased().trimmingCharacters(in: .whitespacesAndNewlines) }
+                .filter { !$0.isEmpty }
+                .map { $0.hasPrefix(".") ? String($0.dropFirst()) : $0 }
+        )
+    }
+
+    func run() throws {
+        runAsyncBlock {
+            try await withServer { server in
+                print("Selecting mailbox \(mailbox)...")
+                _ = try await server.selectMailbox(mailbox)
+                print("Mailbox selected.")
+
+                guard let uids = MessageIdentifierSet<UID>(string: uid) else {
+                    throw ValidationError("Invalid UID list: \(uid)")
+                }
+                let outputURL = URL(fileURLWithPath: out, isDirectory: true)
+                try FileManager.default.createDirectory(
+                    at: outputURL,
+                    withIntermediateDirectories: true,
+                    attributes: nil
+                )
+                print("Output directory: \(outputURL.path)")
+
+                let attachmentExts = attachmentExtensions()
+                print("Fetching message UID(s) \(uid)...")
+                let found = try await downloadAll(
+                    server: server,
+                    uids: uids,
+                    attachmentExts: attachmentExts,
+                    outputURL: outputURL
+                )
+
+                if !found {
+                    print("Message UID(s) \(uid) not found.")
+                }
+            }
+        }
+    }
+
+    private func downloadAll(
+        server: IMAPServer,
+        uids: MessageIdentifierSet<UID>,
+        attachmentExts: Set<String>,
+        outputURL: URL
+    ) async throws -> Bool {
+        var found = false
+        for try await message in server.fetchMessages(using: uids) {
+            found = true
+            let parts = Self.filterAttachments(in: message, extensions: attachmentExts)
+            if parts.isEmpty {
+                print("No matching attachments found for UID \(message.uid?.value ?? 0).")
+                return found
+            }
+            try Self.saveAttachments(parts, to: outputURL)
+        }
+        return found
+    }
+
+    private static func filterAttachments(in message: Message, extensions: Set<String>) -> [MessagePart] {
+        guard !extensions.isEmpty else { return message.attachments }
+        return message.attachments.filter { part in
+            guard let filename = part.filename?.lowercased() else { return false }
+            return extensions.contains(where: { filename.hasSuffix(".\($0)") })
+        }
+    }
+
+    private static func saveAttachments(_ parts: [MessagePart], to outputURL: URL) throws {
+        for part in parts {
+            let filename = part.suggestedFilename
+            let destination = outputURL.appendingPathComponent(filename)
+            print("Saving \(filename)...")
+            guard let data = part.decodedData() ?? part.data else {
+                throw ValidationError("Attachment data missing for \(filename)")
+            }
+            try data.write(to: destination)
+            print("Saved \(filename) to \(destination.path)")
+        }
+    }
+}

Demos/SwiftIMAPCLI/Commands/Fetch.swift

@@ -0,0 +1,157 @@
+import Foundation
+import ArgumentParser
+import SwiftMail
+
+struct Fetch: ParsableCommand {
+    static let configuration = CommandConfiguration(abstract: "Fetch a specific email by UID")
+
+    @Argument(help: "UID(s) of the message (comma-separated; ranges like 1-3 allowed)")
+    var uid: String
+
+    @Option(name: .shortAndLong, help: "Mailbox")
+    var mailbox: String = "INBOX"
+
+    @ArgumentParser.Flag(help: "Download raw RFC 822 message as .eml file")
+    var eml: Bool = false
+
+    @Option(help: "Output directory (saves .eml with --eml, or .txt/.html without)")
+    var out: String?
+
+    func run() throws {
+        runAsyncBlock {
+            try await withServer { server in
+                print("Selecting mailbox \(mailbox)...")
+                _ = try await server.selectMailbox(mailbox)
+                print("Mailbox selected.")
+
+                guard let uids = MessageIdentifierSet<UID>(string: uid) else {
+                    throw ValidationError("Invalid UID list: \(uid)")
+                }
+
+                let outputURL = try Self.prepareOutputURL(out: out)
+                var found = false
+                for try await message in server.fetchMessages(using: uids) {
+                    found = true
+                    try await handle(message: message, server: server, outputURL: outputURL)
+                }
+
+                if !found {
+                    print("Message UID \(uid) not found.")
+                }
+            }
+        }
+    }
+
+    private func handle(
+        message: Message,
+        server: IMAPServer,
+        outputURL: URL?
+    ) async throws {
+        guard let msgUID = message.uid else { return }
+        let safeSubject = Self.safeSubject(for: message)
+
+        if eml {
+            try await Self.saveRawEml(
+                server: server,
+                msgUID: msgUID,
+                safeSubject: safeSubject,
+                outputURL: outputURL
+            )
+        } else if let outputURL {
+            try Self.saveParsedContent(
+                message: message,
+                msgUID: msgUID,
+                safeSubject: safeSubject,
+                outputURL: outputURL
+            )
+        } else {
+            Self.printMessage(message: message, uid: uid)
+        }
+    }
+
+    private static func prepareOutputURL(out: String?) throws -> URL? {
+        guard let out else { return nil }
+        let outputURL = URL(fileURLWithPath: out, isDirectory: true)
+        try FileManager.default.createDirectory(
+            at: outputURL,
+            withIntermediateDirectories: true,
+            attributes: nil
+        )
+        return outputURL
+    }
+
+    private static func safeSubject(for message: Message) -> String? {
+        message.subject.map {
+            String($0
+                .replacingOccurrences(of: "/", with: "-")
+                .replacingOccurrences(of: ":", with: "-")
+                .replacingOccurrences(of: "\\", with: "-")
+                .prefix(80))
+        }
+    }
+
+    private static func saveRawEml(
+        server: IMAPServer,
+        msgUID: UID,
+        safeSubject: String?,
+        outputURL: URL?
+    ) async throws {
+        let data = try await server.fetchRawMessage(identifier: msgUID)
+        let filename = safeSubject.map { "\(msgUID.value)-\($0).eml" } ?? "message-\(msgUID.value).eml"
+        let destination = (outputURL ?? URL(fileURLWithPath: ".")).appendingPathComponent(filename)
+        try data.write(to: destination)
+        print("Saved \(destination.path) (\(data.count) bytes)")
+    }
+
+    private static func saveParsedContent(
+        message: Message,
+        msgUID: UID,
+        safeSubject: String?,
+        outputURL: URL
+    ) throws {
+        var content = ""
+        content += "From: \(message.from ?? "")\n"
+        content += "To: \(message.to.joined(separator: ", "))\n"
+        content += "Subject: \(message.subject ?? "")\n"
+        content += "Date: \(message.date?.description ?? "")\n\n"
+
+        let ext: String
+        if let text = message.textBody {
+            content += text
+            ext = "txt"
+        } else if let html = message.htmlBody {
+            content += html
+            ext = "html"
+        } else {
+            content += "(No body)"
+            ext = "txt"
+        }
+
+        let filename = safeSubject.map { "\(msgUID.value)-\($0).\(ext)" }
+            ?? "message-\(msgUID.value).\(ext)"
+        let destination = outputURL.appendingPathComponent(filename)
+        try content.write(to: destination, atomically: true, encoding: .utf8)
+        print("Saved \(destination.path)")
+    }
+
+    private static func printMessage(message: Message, uid: String) {
+        print("--- Message \(uid) ---")
+        print("From: \(message.from ?? "")")
+        print("Subject: \(message.subject ?? "")")
+        print("Date: \(message.date?.description ?? "")")
+        print("\nBody:")
+        if let text = message.textBody {
+            print(text)
+        } else if let html = message.htmlBody {
+            print("(HTML Body)\n")
+            print(html)
+        }
+
+        if !message.attachments.isEmpty {
+            print("\nAttachments: \(message.attachments.count)")
+            for part in message.attachments {
+                print("- \(part.filename ?? "unnamed") (\(part.contentType))")
+            }
+        }
+    }
+}

Demos/SwiftIMAPCLI/Commands/Folders.swift

@@ -0,0 +1,22 @@
+import Foundation
+import ArgumentParser
+import SwiftMail
+
+struct Folders: ParsableCommand {
+    static let configuration = CommandConfiguration(abstract: "List all mailboxes")
+
+    func run() throws {
+        runAsyncBlock {
+            try await withServer { server in
+                let special = try await server.listSpecialUseMailboxes()
+                print("📂 Special Folders:")
+                if let inbox = special.inbox { print("  - INBOX: \(inbox.name)") }
+                if let drafts = special.drafts { print("  - Drafts: \(drafts.name)") }
+                if let sent = special.sent { print("  - Sent: \(sent.name)") }
+                if let trash = special.trash { print("  - Trash: \(trash.name)") }
+                if let junk = special.junk { print("  - Junk: \(junk.name)") }
+                if let archive = special.archive { print("  - Archive: \(archive.name)") }
+            }
+        }
+    }
+}