contained-app 딥다이브
— Apple Container CLI를 감싸는 네이티브 macOS GUI

2-타겟 클린 아키텍처 — ContainedCore vs Contained

Package.swift가 타겟을 두 개로 분리한다. ContainedCore는 SwiftUI 의존성이 전혀 없는 순수 로직(모델, CLI argv 빌더, JSON 디코더)이라 단위 테스트가 쉽다. Contained는 SwiftUI 앱 셸(뷰, @Observable 스토어, 디자인 시스템)이다. 실제로 Tests/ContainedCoreTests가 Tests/ContainedAppTests와 분리돼 있어, 로직 테스트는 UI 없이 빠르게 돌릴 수 있다.

CLI 3계층 분리 — Commands / Runner / Client

ContainerCommands(순수 argv 문자열 배열 생성, side-effect 없음) → CommandRunner(실제 Process 실행) → ContainerClient(타입 디코딩 파사드)로 나뉜다. 이 분리 덕분에 "어떤 명령어가 만들어지는가"를 CLI 실행 없이 테스트할 수 있고, "Reveal CLI" 기능(실행 전 명령어 미리보기)도 ContainerCommands만 호출해서 구현 가능하다.

// ContainerCommands.swift — 순수 argv 빌더
public enum ContainerCommands {
    static let jsonFormat = ["--format", "json"]

    public static func list(all: Bool) -> [String] {
        var args = ["list"]
        if all { args.append("--all") }
        return args + jsonFormat
    }

    // 비밀번호는 argv가 아닌 stdin으로 — 프로세스 목록에 노출 안 됨
    public static func registryLogin(server: String, username: String) -> [String] {
        ["registry", "login", "--username", username,
         "--password-stdin", server]
    }
}

Process/Pipe 래핑 — 교착 방지 + 스트리밍

CommandRunner는 Process와 Pipe로 CLI를 실행하되, stdout/stderr를 동시에 읽어 한쪽 파이프 버퍼가 가득 차서 교착(deadlock)되는 걸 막는다. 로그 tail이나 이미지 pull 진행률처럼 실시간 스트림이 필요한 경우엔 AsyncThrowingStream으로 감싸고, 소비 측 Task가 취소되면 onTermination에서 자식 프로세스를 terminate()해 좀비 프로세스를 방지한다.

// CommandRunner.swift 핵심 구조 (요약)
public final class CommandRunner: CommandRunning {
    public func run(_ arguments: [String], stdin: Data?) async throws -> Data {
        try await withCheckedThrowingContinuation { continuation in
            DispatchQueue.global(qos: .userInitiated).async {
                let process = Process()
                process.executableURL = self.executableURL
                process.arguments = arguments
                let outPipe = Pipe(); let errPipe = Pipe()
                process.standardOutput = outPipe
                process.standardError = errPipe
                try? process.run()
                // stdout/stderr 동시 읽기 → 교착 방지
                process.waitUntilExit()
                continuation.resume(returning: /* 읽은 데이터 */ Data())
            }
        }
    }

    // 스트리밍: 취소 시 자식 프로세스 자동 종료
    public func stream(_ arguments: [String]) -> AsyncThrowingStream<String, Error> {
        AsyncThrowingStream { continuation in
            continuation.onTermination = { _ in process.terminate() }
        }
    }
}

앱 관리형 기능 — RestartWatchdog으로 CLI 공백 메우기

container CLI엔 Docker의 --restart always 같은 네이티브 재시작 정책이 없다. Contained는 매 새로고침(refresh) 주기마다 컨테이너 상태를 이전 상태와 diff해서, running → stopped로 전환됐고 contained.restart 라벨이 붙은 컨테이너를 감지하면 start 명령을 재실행한다. 재시도는 최대 5회, 지수 백오프로 제한해 크래시 루프를 방지한다.

// RestartWatchdog.swift — 핵심 아이디어
/// container CLI엔 네이티브 --restart가 없으므로, 매 refresh마다
/// 상태를 diff해서 running→stopped 전환 + contained.restart 라벨이
/// always/on-failure인 컨테이너에 한해 start를 재발행한다.
@MainActor
final class RestartWatchdog {
    private let maxRetries = 5
    private var lastState: [String: RuntimeStatus] = [:]
    private var attempts: [String: Int] = [:]
    private var nextEligible: [String: Date] = [:]
}

Contained는 "GUI가 CLI를 대체하는 게 아니라 보조한다"는 철학을 코드로 구현한 좋은 사례다. ContainerCommands(순수 argv 빌더) → CommandRunner(실행) → ContainerClient(디코딩)의 3계층 분리를 그대로 따라 하면, 어떤 CLI 도구든 안전하게 GUI로 감쌀 수 있다.

배울 것: 순수 함수로 명령어 인자 배열 만들기(테스트 용이), "실행 전 미리보기" 기능을 위한 계층 분리, CLI 출력(JSON) 디코딩과 UI 모델 분리.

CommandRunner.swift는 Foundation의 Process와 Pipe를 다루는 실전 패턴을 보여준다. stdout/stderr를 동시에 읽어야 교착을 막을 수 있다는 것, stdin으로 비밀번호를 흘려보내 argv 노출을 피하는 것, 스트리밍 중 Task 취소 시 자식 프로세스를 확실히 종료(terminate())하는 것까지 — 프로덕션 수준의 서브프로세스 관리 코드다.

배울 것: Process.standardOutput/standardError 파이프 연결, withCheckedThrowingContinuation으로 콜백 API를 async/await로 브릿지, AsyncThrowingStream과 onTermination으로 리소스 정리 보장.

ObservableObject + @Published 구식 패턴 대신 Swift 최신 @Observable 매크로를 전역적으로 사용한다. AppModel, ContainersStore 등 모든 스토어가 @MainActor @Observable final class로 선언되고, .environment(app)으로 SwiftUI 뷰 트리에 주입된다.

배울 것: @Observable과 ObservableObject의 차이(세밀한 프로퍼티 단위 추적, 보일러플레이트 감소), @MainActor 격리로 UI 업데이트 스레드 안전성 보장, environment 기반 의존성 주입 패턴.

순수 SwiftUI 앱이라도 완전한 터미널 에뮬레이션처럼 SwiftUI가 못 하는 기능은 성숙한 AppKit 라이브러리(SwiftTerm)를 브릿지해서 해결한다. makeNSView/updateNSView/dismantleNSView 생명주기를 정확히 구현하면 SwiftUI와 AppKit을 매끄럽게 공존시킬 수 있다.

배울 것: NSViewRepresentable 프로토콜 구현, Coordinator 패턴으로 델리게이트 연결, 뷰 해제 시 리소스(자식 프로세스) 정리 타이밍.

Xcode 프로젝트 없이 SPM만으로 배포 가능한 .app 번들을 만드는 전체 파이프라인을 갖추고 있다. scripts/bundle.sh가 swift build 산출물을 번들링하고, scripts/make-dmg.sh가 채널별(stable/beta/nightly) 배경 이미지가 다른 DMG를 생성하며, Sparkle이 appcast.xml로 자동 업데이트를 제공한다.

배울 것: SPM 실행형 타겟을 macOS .app 번들로 패키징하는 절차, Sparkle 프레임워크로 자동 업데이트 구현, GitHub Actions로 3채널(Stable/Beta/Nightly) 빌드 파이프라인 구성, 코드 서명 없이/있이의 배포 차이.

ContainedCore(순수 로직)와 Contained(SwiftUI 셸)의 타겟 분리는 "테스트하기 쉬운 코드"를 설계하는 원칙을 보여준다. Tests/ContainedCoreTests의 Fixtures에는 실제 container list --format json 응답을 흉내낸 JSON 픽스처가 있어, CLI 실행 없이도 디코딩 로직을 검증할 수 있다.

배울 것: 비즈니스 로직과 UI 프레임워크 의존성 분리, JSON 픽스처 기반 디코더 테스트, 멀티 타겟 SPM 패키지 설계.

실습 1 — Apple container CLI 설치 후 Contained로 첫 컨테이너 실행1/4

Apple Silicon Mac(macOS 26+)에서 Apple의 container CLI를 먼저 설치하고, Contained 앱을 빌드/실행해 alpine 이미지를 pull한 뒤 컨테이너를 실행해본다.

# 1) Apple container CLI 설치 (공식 저장소 릴리스 참고)
container --version    # 1.0.x 확인

# 2) Contained 클론 & 빌드
git clone https://github.com/tdeverx/contained-app
cd contained-app
swift build
./scripts/bundle.sh debug
open Contained.app

확인 포인트: 앱 실행 시 부트스트랩 화면이 "ready" 상태로 넘어가는지, 컨테이너 카드가 그리드에 나타나는지 확인.

실습 2 — "Reveal CLI"로 실제 명령어 비교해보기2/4

Run 폼에서 포트 매핑·볼륨·환경변수를 채운 뒤 "Reveal CLI" 버튼으로 미리보기 명령어를 확인하고, 터미널에서 똑같은 명령어를 직접 쳐서 결과가 동일한지 비교한다.

# 예상되는 미리보기 명령어 형태
container run --detach --name my-nginx \
  --publish 8080:80 \
  --volume ~/data:/usr/share/nginx/html \
  --env FOO=bar \
  nginx

확인 포인트: RunSpec.arguments()가 만든 argv와 실제 터미널 명령어가 정확히 일치하는지, GUI 폼 필드와 CLI 플래그의 1:1 매핑 관계를 이해한다.

실습 3 — 나만의 CLI 래퍼 앱 만들기 (CommandRunner 패턴 재사용)3/4

Contained의 CommandRunner/ContainerCommands 계층 분리를 참고해, 다른 CLI 도구(예: git, docker, 자신이 만든 스크립트)를 감싸는 미니 SwiftUI 앱을 만들어본다.

// 순수 argv 빌더 (테스트 가능)
enum GitCommands {
    static func status() -> [String] { ["status", "--short"] }
    static func log(count: Int) -> [String] { ["log", "-\(count)", "--oneline"] }
}

// 실제 실행은 CommandRunner가 담당 (Contained 코드 참고)

확인 포인트: stdout/stderr를 동시에 읽지 않으면 어떤 상황에서 교착이 발생하는지 직접 재현해본다(큰 출력을 만드는 명령어로 테스트).

실습 4 — 나만의 재시작 워치독 구현하기4/4

RestartWatchdog.swift를 참고해, 특정 라벨이 붙은 컨테이너가 크래시하면 최대 N회까지 지수 백오프로 재시작하는 로직을 직접 구현해본다. Contained 소스의 Tests/ContainedAppTests에서 관련 테스트가 있는지 찾아 패턴을 검증한다.

@MainActor
final class MyWatchdog {
    private let maxRetries = 5
    private var attempts: [String: Int] = [:]
    private var nextEligible: [String: Date] = [:]

    func checkAndRestart(previous: [String: RuntimeStatus],
                          current: [String: RuntimeStatus]) async {
        // running → stopped 전환 감지 후 지수 백오프로 재시작
    }
}

확인 포인트: 백오프 시간이 지수적으로 늘어나는지, maxRetries 초과 시 재시작을 포기하고 상태를 사용자에게 알리는지 확인한다.

목표: Swift 문법(옵셔널, 구조체 vs 클래스, 프로토콜), SwiftUI로 간단한 화면 만들기.

자료: Apple 공식 "The Swift Programming Language", "Introducing SwiftUI" 튜토리얼(developer.apple.com).

실습: 카드 그리드 UI를 SwiftUI LazyVGrid로 만들어보기. Contained의 ContainersGridView 구조 참고.

목표: @Observable 매크로의 동작 원리, environment 기반 의존성 주입 이해.

자료: WWDC "Discover Observation in SwiftUI" 세션, Apple Observation 프레임워크 문서.

실습: AppModel과 유사한 전역 상태 스토어를 만들어 여러 뷰에서 공유해보기.

목표: Process, Pipe, FileHandle로 외부 CLI를 실행하고 출력을 캡처하는 법.

자료: Apple Foundation Process 클래스 문서, "Swift에서 셸 명령어 실행하기" 관련 블로그 글들.

실습: CommandRunner.swift를 그대로 따라 작성해보고, 교착 상황을 의도적으로 재현 후 해결한다.

목표: 컨테이너와 VM의 차이, Apple의 경량 VM 기반 컨테이너 런타임이 Docker와 어떻게 다른지 이해.

자료: github.com/apple/container README 및 아키텍처 문서, Docker 공식 문서의 컨테이너 vs VM 설명.

실습: container CLI만으로 (GUI 없이) 이미지 pull → run → exec → logs 전체 흐름을 손으로 실행해보고, Contained가 이를 어떻게 GUI로 매핑했는지 소스와 대조한다.

목표: SwiftUI에서 AppKit 뷰를 통합하는 방법, 생명주기 관리.

자료: Apple NSViewRepresentable 문서, SwiftTerm 저장소(migueldeicaza/SwiftTerm) README.

실습: TerminalTab.swift를 참고해 간단한 텍스트 뷰를 AppKit NSTextView로 브릿지해보기.

목표: SPM 프로젝트를 .app/.dmg로 패키징하고 Sparkle로 자동 업데이트를 붙이는 전체 흐름.

자료: Sparkle 공식 문서(sparkle-project.org), scripts/bundle.sh·scripts/make-dmg.sh·scripts/appcast.sh 소스 정독.

실습: 자신의 SPM 실행형 프로젝트를 번들링해 .app으로 만들고, GitHub Actions로 릴리스 자동화 워크플로우를 구성해본다.