From c9d374ade6f1d073494e8341072a3557f8cdcae2 Mon Sep 17 00:00:00 2001
From: altair823 <kimth0734@gmail.com>
Date: Thu, 7 May 2026 00:23:07 +0900
Subject: [PATCH] =?UTF-8?q?docs(v027):=20dist:linux=201=EC=B0=A8=20?=
 =?UTF-8?q?=EB=B9=8C=EB=93=9C=20=EC=8B=9C=EB=8F=84=20=EA=B2=B0=EA=B3=BC=20?=
 =?UTF-8?q?(Windows=20=ED=98=B8=EC=8A=A4=ED=8A=B8)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../2026-05-06-v027-cross-platform-design.md  | 39 +++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs/superpowers/specs/2026-05-06-v027-cross-platform-design.md b/docs/superpowers/specs/2026-05-06-v027-cross-platform-design.md
index e4d0972..ab2102b 100644
--- a/docs/superpowers/specs/2026-05-06-v027-cross-platform-design.md
+++ b/docs/superpowers/specs/2026-05-06-v027-cross-platform-design.md
@@ -357,6 +357,45 @@ ipcMain.handle('settings:autostart-state', async () => {
 
 ---
 
+### v0.2.7 Linux 빌드 1차 시도 결과 (2026-05-07, Windows 호스트)
+
+`npm run dist:linux` 실행 — Windows 11 호스트.
+
+**진행 단계:**
+
+- ✅ predist:linux (electron rebuild + electron-vite build) — 성공
+- ✅ electron-builder linux x64 패키징 prep — 성공
+- ✅ electron-v41.3.0-linux-x64.zip 다운로드 (117 MB)
+- ✅ `dist/linux-unpacked/` 스테이징 생성 — 322 MB (electron + native modules + app)
+- ✅ appimage-12.0.1.7z 다운로드 (mksquashfs 등 Linux 유저랜드 도구 캐시)
+- ⚠️ **AppImage 패키징 실패** — `mksquashfs` 실행 불가
+- ⏭️ **deb 패키징은 시도조차 못함** (AppImage 실패로 빌드 중단)
+
+**핵심 에러:**
+
+```text
+⨯ cannot execute  cause=exec: "C:\Users\...\electron-builder\Cache\appimage\appimage-12.0.1\linux-x64\mksquashfs": file does not exist
+⨯ failed to build AppImage  error=...app-builder.exe process failed ERR_ELECTRON_BUILDER_CANNOT_EXECUTE
+Exit code: 2
+```
+
+**진단:** `mksquashfs` 파일은 캐시에 존재하나 (270 KB Linux ELF 바이너리), Windows 가 ELF 를 실행 불가 → electron-builder 가 "file does not exist" 로 보고. AppImage cross-build from Windows 는 **근본적으로 불가능** (WSL/Docker/Linux/Mac 호스트 필요).
+
+**결론:**
+
+- AppImage: ⚠️ 실패 (Windows 호스트는 mksquashfs ELF 실행 불가 — 환경 제약)
+- deb: ⚠️ 미시도 (`dpkg-deb` + `fakeroot` 부재 추정. AppImage 실패로 도달 못함)
+
+**Fallback 결정:** Mac (사용자 업무 호스트) 또는 Linux/WSL/Docker 핸드오프 필수. Windows 단독으로는 v0.2.7 Linux 산출물 생성 불가. plan Task 3 은 "시도 + 결과 기록" 이 핵심이었고, **macOS 후속 시도가 본 빌드** — Windows 시도는 환경 한계 확인용.
+
+**권장 후속:**
+
+1. 사용자 macOS 업무 호스트에서 동일 명령 (`npm run dist:linux`) 재시도. brew 로 `dpkg` + `fakeroot` 사전 설치 (`brew install dpkg`). AppImage 는 macOS 에서 정상 cross-build 가능 (mksquashfs Mach-O 바이너리 caching).
+2. macOS 에서도 deb 가 실패할 경우 — v0.2.7 scope 를 **AppImage only** 로 축소, deb 는 v0.2.8 또는 Docker `electronuserland/builder` 환경으로 이동. package.json `linux.target` 에서 deb 제거하거나 별도 task 로 분리.
+3. 향후 자동화: GitHub Actions / Gitea Actions 에서 ubuntu-latest runner 로 Linux build 자동화 (현 수동 cross-build 환경 의존성 제거).
+
+---
+
 ## 12. v0.2.7 후
 
 **잔여 backlog (24건)** — `docs/superpowers/v024-backlog.md`: