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로 증명한다

이 부분이 진짜 인상적이다. "우리는 텔레메트리(사용 통계 수집)를 하지 않는다"는 주장은 누구나 할 수 있다. Mac Sai는 .github/workflows/ci.yml에 security-audit 잡을 두고, UpdaterModule.swift 바깥에서 URLSession·NSURLConnection 사용이 발견되면 경고·실패시킨다.

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                     # 486개 테스트 — 여기가 학습 시작점으로 좋다
./scripts/build-dmg.sh         # 배포용 DMG (서명 인증서 필요)

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

grep -rl "NSXPCListener" Sources/          # 결과 0줄
find . -iname '*.entitlements'              # 결과 없음
cat Sources/MacCleanKit/MalwareSignatures.swift
ls Sources/ | grep -i helper                # MacCleanHelper 없음

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

10핵심 키워드 사전

11참고 링크

저장소 · 배포

• 저장소 — github.com/iliyami/MacSai (BSD-3-Clause)
• 릴리스 — releases (최신 태그 v1.16.0, 2026-07-11)
• 이슈 — 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 — 하드코딩 패턴 19개
• 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보다 앞선다고 저장소가 인정