iliyami/MacSai 딥다이브
— 공짜 CleanMyMac을 표방한 Swift 6 네이티브 앱, 그 안의 진짜 설계

1프로젝트 한 줄 요약

맥을 오래 쓰면 ~/Library/Caches에 수 GB가 쌓이고, 지운 줄 알았던 앱의 설정 파일이 여기저기 남고, 사진 폴더 어딘가에 같은 파일이 세 벌씩 존재한다. 이걸 해결해준다는 앱은 원래 유료 시장이었다 — CleanMyMac이 연 $39.95다. Mac Sai는 그 기능 목록을 거의 그대로 복제해 무료·오픈소스로 내놓았고, 여기에 CleanMyMac에 없는 디스크 트리맵 시각화(Space Lens)를 얹었다.

2왜 지금 주목받는가

2-1. 최초 분석 당시의 경쟁 구도

README에 CleanMyMac·Pearcleaner·PureMac·OnyX·Mole와의 비교표가 있다. 마케팅 메시지가 명확하다는 뜻이고, 트렌딩에 필요한 "한 줄로 설명되는 차별점"을 확보했다는 뜻이다.

※ OnyX는 유지보수 스크립트 항목에서 Mac Sai보다 깊다고 저장소가 스스로 인정한다.

2-2. 주장을 검사하는 CI와 그 한계

현재 .github/workflows/ci.yml의 Build & Test는 빌드 후 scripts/check-network-surface.sh를 실행합니다. 소스의 URLSession 문자열만 찾던 설명 대신, 실제 바이너리의 nm -u와 strings 결과에서 금지 네트워크 심볼과 추적 SDK·도메인 패턴을 검사합니다. 공개한 업데이트 주소가 없으면 경고하며 발견한 URL도 출력합니다.

코드가 모든 미공개 URL을 허용 목록과 엄격히 대조하는 것은 아닙니다. 특정 패턴을 잡는 검사이므로 텔레메트리 부재를 완전히 증명한다고 해석하면 안 됩니다. 별도 security-audit 잡의 삭제 경로 검색도 일부는 경고 수준입니다. 검사 구현과 README의 주장 사이 경계를 읽는 것이 학습 포인트입니다.

2-3. 배포 경로가 이미 정돈됨

brew install --cask mac-sai — 개인 tap이 아니라 공식 Homebrew cask다. 7주 된 프로젝트가 공식 cask에 올라갔다는 건 배포·버전 관리가 실제로 굴러간다는 신호다. 릴리스는 태그 트리거(release.yml)로 서명·공증까지 자동화돼 있다.

2-4. 외부 기여가 실제로 들어온다

커밋 로그에 rarnu, lukman48 같은 외부 기여자의 머지가 보인다. Space Lens의 파일 타입별 색상 구분은 PR #110(2026-07-11)로 들어온 외부 기여다. "한 사람 취미 프로젝트"에서 "커뮤니티 프로젝트"로 넘어가는 구간에 있다.

3기술 스택 전체 지도

3-1. 한눈에

3-2. 세 개의 타깃

// Package.swift — 실제 구성
products: [
  .executable(name: "MacClean",     targets: ["MacClean"]),      // 본체 GUI 앱
  .executable(name: "MacCleanMenu", targets: ["MacCleanMenu"]),  // 메뉴바 위젯 (별도 프로세스)
  .library(   name: "MacCleanKit",  targets: ["MacCleanKit"]),   // 순수 로직 공유 프레임워크
],
dependencies: [
  .package(url: "https://github.com/groue/GRDB.swift.git", from: "7.0.0")
]

3-3. 상태 관리는 이주 중이다

코드베이스가 Combine 시대의 ObservableObject에서 Swift의 새 @Observable 매크로로 옮겨가는 중간에 멈춰 있다. 학습자에게는 오히려 좋은 표본이다 — 한 저장소 안에서 옛 방식과 새 방식을 나란히 비교할 수 있다.

// ViewModels/FileHandlerViewModel.swift — 구(Combine) 방식
@MainActor
public final class FileHandlerViewModel: ObservableObject { ... }

// ViewModels/SystemJunkViewModel.swift — 신(Observation 프레임워크) 방식
@MainActor @Observable
final class SystemJunkViewModel { ... }

4아키텍처 심화 분석

4-1. 시스템 구조도

4-2. 핵심 설계 패턴 ① — "순수 로직"과 "부작용"의 분리

이 코드베이스에서 가장 일관되게 지켜지는 규칙이다. 판단은 MacCleanKit에, 실제 파일 I/O는 MacClean/Modules에 둔다.

4-3. 핵심 설계 패턴 ② — 액터로 감싼 스캐너, TaskGroup으로 병렬화한 해싱

순진하게 생각하면 "파일 순회를 병렬화"할 것 같지만 반대다. FileTreeScanner는 단일 액터로 순차 순회하고, 병렬화는 해싱 단계에서만 일어난다.

// Core/Scanner/FileTreeScanner.swift (요지)
actor FileTreeScanner {
  nonisolated func scan(...) -> AsyncStream<FileItem> {
    // FileManager.enumerator 로 순차 순회 (getattrlistbulk 아님)
    // 매 반복마다 Task.isCancelled 확인 → 취소 즉시 응답
    // 200개마다 await Task.yield() → UI 멈춤 방지
  }
}

4-4. 프로세스 간 통신 — XPC도 App Group도 아닌 "이름 붙인 UserDefaults"

본체 앱과 메뉴바 위젯은 별개 프로세스다. 마지막 악성코드 스캔 시각 같은 상태를 공유해야 하는데, 여기서 정석을 버리고 실용을 택했다. 그리고 그 선택을 코드 주석에 대놓고 적어뒀다.

// MacCleanKit/SharedAppState.swift
/// 두 프로세스가 같은 suite 를 이름으로 열면, macOS 가
/// ~/Library/Preferences/com.macclean.shared.plist 하나로 뒷받침해준다.
/// App Group 이 macOS 정석 패턴이지만, 이름 붙인 suite 가
/// 더 단순하고 서명 구성과 무관하게 동작한다.
public enum SharedAppState {
  public static let suiteName = "com.macclean.shared"
  public static var defaults: UserDefaults { UserDefaults(suiteName: suiteName) ?? .standard }
}

4-5. README와 코드가 어긋나는 지점 — 특권 헬퍼 이야기

이 문서에서 가장 중요한 대목이다. README의 아키텍처 다이어그램은 이렇게 말한다:

그런데 저장소에는 MacCleanHelper라는 타깃도, 디렉토리도, NSXPCListener 사용처도 없다. 실제 특권 상승 경로는 이것이다:

// Modules/Maintenance/MaintenanceModule.swift
let script = "do shell script \"\(escaped)\" with administrator privileges"
let result = await runProcess(task: task, command: "/usr/bin/osascript", args: ["-e", script])
// 사용자가 취소하면 osascript 가 -128 / "User canceled." 반환

5디렉토리 구조 해부

6학습 포인트

6-1. 스쿼리파이드 트리맵 — 논문을 230줄 Swift로

MacCleanKit/SquarifiedTreemap.swift는 Bruls·Huizing·van Wijk(2000)의 알고리즘을 처음부터 구현한다. 학술 논문의 레이아웃 알고리즘을 순수 함수로 옮기는 훌륭한 표본이다.

// MacCleanKit/SquarifiedTreemap.swift
public static func layout(nodes: [TreemapNode], in rect: CGRect) -> [TreemapRect] {
  guard !nodes.isEmpty, rect.width > 0, rect.height > 0 else { return [] }
  let totalSize = nodes.reduce(0.0) { $0 + Double($1.size) }
  let sorted = nodes.sorted { $0.size > $1.size }          // 큰 것부터
  let areas  = sorted.map { Double($0.size) / totalSize * Double(rect.width * rect.height) }
  var results: [TreemapRect] = []
  var remaining = Array(zip(sorted, areas))
  var currentRect = rect
  while !remaining.isEmpty {
    let (row, rest, newRect) = squarify(remaining: remaining, in: currentRect)
    results.append(contentsOf: row); remaining = rest; currentRect = newRect
  }
  return results
}

6-2. 중복 탐지 — 4단계 깔때기로 O(n²)를 피한다

모든 파일 쌍을 비교하면 파일 10만 개에 50억 번 비교다. Mac Sai는 점점 비싼 검사로 좁혀간다.

// Modules/Duplicates/DuplicatesModule.swift — 2단계 병렬 부분 해싱
let partialResults = await withTaskGroup(of: (key: String, item: FileItem)?.self) {
  group -> [(key: String, item: FileItem)] in
  for sizeGroup in candidates {
    for item in sizeGroup {
      group.addTask {
        guard let hash = Self.partialHash(item.url) else { return nil }
        return (key: "\(item.size)-\(hash)", item: item)
      }
    }
  }
  var out: [(key: String, item: FileItem)] = []
  for await r in group { if let r { out.append(r) } }
  return out
}

6-3. macOS firmlink 정규화 — 이걸 모르면 안전 검사가 뚫린다

macOS Catalina 이후 시스템 볼륨이 읽기 전용으로 분리되면서 /var와 /private/var가 같은 위치를 가리키는 기묘한 이중 표기가 생겼다. MacCleanKit/SafetyGuard.swift의 canonicalizeMacOSFirmlinks가 이를 통일한다.

6-4. TOCTOU 방어 — 검사와 사용 사이의 틈

SafetyGuard.validatePath는 삭제 직전에 심볼릭 링크를 다시 해석하고 경로 구성요소 접두사를 비교해 이 공격을 막는다. 안전 검사를 "한 번 하고 결과를 캐싱"하지 않는다는 규율이 핵심이다.

6-5. 실제 버그 수정 커밋이 최고의 교재다

클론 시점의 HEAD 커밋 b7cb859는 이렇다: "Shredder: 실제로 덮어쓰지 않은 안전 삭제를 성공으로 보고하지 않기 (#112)".

// Modules/Shredder/ShredderModule.swift (수정 후)
private func secureOverwrite(_ url: URL) throws {
  // SSD 에서는 삭제 후 TRIM 이 물리 블록을 알아서 0으로 만든다.
  // 이 덮어쓰기는 best-effort — 진짜 보안이 필요하면 FileVault 를 권장.
  guard values.isSymbolicLink != true else {
    throw SafetyGuard.SafetyError.symlinkTarget(url.path(percentEncoded: false))
  }
  let handle = try FileHandle(forWritingTo: url)   // 실패를 전파 — 조용히 성공하지 않음
  ...
}

6-6. 나머지 학습 포인트 요약

7시스템 요구사항 · 설치

설치 · 빌드

# 1) 일반 사용자 — Homebrew (공식 cask, 개인 tap 아님)
brew install --cask mac-sai
# 예전에 개인 tap 을 썼다면 먼저 정리
brew untap iliyami/macsai

# 2) 소스에서 빌드 (코드 읽기가 목적이라면 이쪽)
git clone --depth 1 https://github.com/iliyami/MacSai
cd MacSai
swift build                    # 의존성은 GRDB 하나만 받아온다
swift test                     # 테스트 실행 예시. 이번 분석에서는 실행하지 않음
./scripts/build-dmg.sh         # 배포용 DMG (서명 인증서 필요)

8직접 해볼 수 있는 실습 과제

PIN=d4ccd8a71b4731b910e8bd893ef11a8095cc56f4
git show "$PIN:Sources/MacCleanKit/MalwareSignatures.swift"
git show "$PIN:Sources/MacCleanKit/XProtectDatabase.swift"
git show "$PIN:Sources/MacClean/Modules/Malware/MalwareModule.swift"

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

저장소 · 배포

• 저장소 — github.com/iliyami/MacSai (BSD-3-Clause)
• 릴리스 — releases (관측한 최신 공개 태그 v1.25.7, 2026-10-19; 분석 main과 구분)
• 이슈 — issues (이 문서가 언급한 #98 회사명 오매칭, #112 shredder 거짓 보고)
• 설치 — brew install --cask mac-sai

이 문서가 인용한 핵심 파일

• Sources/MacCleanKit/SquarifiedTreemap.swift — 트리맵 알고리즘
• Sources/MacCleanKit/SafetyGuard.swift — firmlink 정규화 · TOCTOU 방어
• Sources/MacCleanKit/DuplicateDetection.swift — 원본 선택 규칙
• Sources/MacCleanKit/MalwareSignatures.swift — 휴리스틱 + XProtect 해시
• Sources/MacCleanKit/SharedAppState.swift — 프로세스 간 상태 공유
• Sources/MacClean/Core/Scanner/FileTreeScanner.swift — 액터 스캐너
• Sources/MacClean/Modules/Duplicates/DuplicatesModule.swift — 병렬 해싱
• Sources/MacClean/Modules/Shredder/ShredderModule.swift — 안전 삭제
• Sources/MacClean/Modules/Maintenance/MaintenanceModule.swift — 특권 실행 경로
• .github/workflows/ci.yml — security-audit 잡

배경 지식

• Swift 동시성 — The Swift Programming Language: Concurrency
• Observation 프레임워크 — developer.apple.com/documentation/observation
• 공증 — Notarizing macOS software before distribution
• GRDB — groue/GRDB.swift
• 트리맵 원논문 — Bruls, Huizing, van Wijk, "Squarified Treemaps" (2000)

비교 대상

• Pearcleaner — 앱 삭제 특화 오픈소스 (SwiftUI)
• Mole — 경량 맥 정리 도구
• OnyX — 유지보수 스크립트 깊이에서 Mac Sai보다 앞선다고 저장소가 인정