From c256d3e50b2bd6e9b2e212854565ddcb95c3fcaf Mon Sep 17 00:00:00 2001 From: BoxLogoDev <86134843+BoxLogoDev@users.noreply.github.com> Date: Thu, 20 Aug 2026 16:50:26 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EC=84=9C=EB=B8=8C=ED=94=84=EB=A1=9C?= =?UTF-8?q?=EC=84=B8=EC=8A=A4=20=EC=84=9C=EB=B2=84=20=EA=B2=B0=EC=A0=95=20?= =?UTF-8?q?=EC=A0=95=EC=A0=95=20=E2=80=94=20v2.4.1=20=EC=84=A4=EC=B9=98?= =?UTF-8?q?=EB=B3=B8=EC=97=90=EC=84=9C=20=EC=97=AC=EC=A0=84=ED=9E=88=20?= =?UTF-8?q?=EB=AF=B8=ED=95=B4=EC=86=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit v2.4.1 을 릴리스하고 설치본을 실측한 결과, dist/resources/ 에 pi-agent-server 와 session-mcp-server 가 여전히 없다. 결정 레코드가 "수리 완료"라고 적은 것은 사실이 아니었다. 결정 자체가 틀린 게 아니라 적용 지점이 틀렸다. 자산 복사 스크립트가 두 개고, 수리는 electron-build-resources.ts 에 들어갔는데 설치파일을 만드는 build-win.ps1 은 copy-assets.ts 만 부른다. copy-assets.ts 396행 주석의 "Single source of truth" 는 사실이 아니다. 수리를 build-win.ps1 로 옮기려 했으나 pi-agent-server 가 로컬에서 빌드되지 않는다. 추적 결과 루트 node_modules 를 npm 과 bun 이 나눠 쓰면서 @aws-crypto 서브트리가 통째로 잘려 있었다 — 루트 package.json 의 workspaces 는 apps/desktop 을 포함하지 않는데 bun 이 루트를 모노레포 루트로 오인해 스토어를 거기 만든다. 검증 안 된 빌드 단계를 워크플로에 넣으면 방금 복구한 파이프라인이 다시 깨지므로 여기서 멈춘다. 조사 중 node_modules 에 임시 배치했던 파일은 원상 복구했다. Co-Authored-By: Claude Opus 5 (1M context) --- STATE.md | 35 ++++++---- ...08-19-subprocess-servers-must-be-copied.md | 67 ++++++++++++++++++- 2 files changed, 87 insertions(+), 15 deletions(-) diff --git a/STATE.md b/STATE.md index 341b4cc..3cf69b4 100644 --- a/STATE.md +++ b/STATE.md @@ -20,24 +20,35 @@ v2.4.0 이 npm 에 라이브인 상태에서, 데스크톱(Electron) 쪽 미완 지시서도 정리했다: `AGENTS.md` 가 정본이 되고 `CLAUDE.md`·`.windsurfrules` 는 포인터로 축소. 그 여파로 규칙을 코드로 읽던 3곳(eval 하니스·MCP 리소스·데스크톱 자산 복사)을 함께 정렬했다. -**릴리스 파이프라인이 두 번 막혔다가 뚫렸다** (PR #45, #47). 둘 다 "로컬은 통과, CI 만 실패" 형태였다 — -`build-win.ps1` 이 BOM 없는 UTF-8 이라 영어 로케일 러너에서만 파서가 깨졌고, -`bun install --ignore-scripts` 가 `@vscode/ripgrep`·`electron` 의 바이너리 postinstall 을 건너뛰어 -설치 시점이 아니라 빌드 도중에 엉뚱한 메시지로 터졌다. 이 캐스케이드 전체는 -`~/.claude/.../memory/sapstack-release-cascade.md` 에 남겼다. +**릴리스 파이프라인을 네 번에 걸쳐 뚫었다** (PR #45, #47, #48, #49). 데스크톱 잡이 추가된 뒤 +이 파이프라인이 끝까지 간 적이 한 번도 없었고, 결함이 **순차적으로만** 드러났다 — +앞의 것을 고쳐야 다음 것이 보인다: + +1. `build-win.ps1` 이 BOM 없는 UTF-8 → 영어 로케일 러너에서만 파서가 깨짐 (#45) +2. `bun install --ignore-scripts` 가 `@vscode/ripgrep`·`electron` 바이너리 postinstall 을 건너뜀 (#47) +3. `electron-builder` 가 태그 푸시에서 스스로 업로드하려다 `GH_TOKEN` 요구 (#48) +4. `npm publish` 실패가 `Create GitHub Release` 를 skip 시켜 데스크톱 배포까지 막음 (#49) + +네 개 다 "로컬은 통과, CI 만 실패" 형태다. 전체 캐스케이드는 +`~/.claude/.../memory/sapstack-release-cascade.md`, 4번의 판단 근거는 +`decisions/active/2026-08-19-workflow-owns-release-upload.md` 에 있다. ## 열린 것 -| 항목 | 막힌 이유 | 다음 행동 | -| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| **🔴 설치본에 pi-agent-server 가 없다 — 로컬 채팅 전면 불가** | 빌드가 `packages/*/dist` 를 `dist/resources/` 로 복사하지 않았다. 설치본 실측으로 `pi-agent-server`·`llama` 부재 확인. 사용자 화면에서 `piServerPath not configured` 재현됨 | **소스는 수리 완료**(`electron-build-resources.ts` 가 복사 + 누락 시 빌드 실패). **새 릴리스를 만들어야 실제 해소된다** — 설치본은 수리 전 빌드 | -| **로컬 LLM 실기기 검증** | 위 릴리스 후에만 의미 있다 | 새 빌드 설치 → 모델팩을 `~/.sapstack/models/` 에 넣고 채팅 1턴 | -| GGUF 가중치 미번들 | 라이선스·용량 문제로 설치파일에 못 넣음 | 운영자가 USB 반입. 권장 모델팩 결정 필요 | -| Qwen3 8B "권장" 판정 보류 | 개발 머신 실측 0.75 tok/s — 타깃 사양(16GB 노트북) 미실측 | 실기기 측정 후 문서의 "장비에 따라 선택" 문구 확정 | +| 항목 | 막힌 이유 | 다음 행동 | +| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **🔴 설치본에 pi-agent-server 가 없다 — 로컬 채팅 전면 불가 (v2.4.1 에서도 미해소)** | 수리를 `scripts/electron-build-resources.ts` 에 넣었는데 **`build-win.ps1` 은 그걸 부르지 않는다** — 조각 빌드 + `copy-assets.ts`(정적 자산만)만 돈다. 2.4.1 설치본 실측으로 재확인. 게다가 `pi-agent-server` 는 로컬 빌드 자체가 안 된다(`@aws-crypto/crc32` 미해석, 루트 `.bun` 스토어 누락) | ① 클린 체크아웃에서 `bun install` → `bun run server:build:subprocess` 통과 여부 확인 → ② 통과하면 `build-win.ps1` 에 `server:build:subprocess` + `electron:build:resources` 추가. 검증 전 워크플로에 넣지 말 것 | +| **로컬 LLM 실기기 검증** | 위 항목이 먼저다. 2.4.1 설치본으로는 여전히 못 한다 | 서브프로세스 서버가 실린 빌드가 나온 뒤 → 모델팩을 `~/.sapstack/models/` 에 넣고 채팅 1턴 | +| **🟡 npm 토큰 만료 — MCP 2.4.1 미발행** | `Publish MCP to npm` 이 `E404 PUT` 로 실패. 패키지는 존재하므로(2.4.0) 스코프가 아니라 토큰 문제 — npm 은 권한 부족에도 404 를 준다 | **사용자 조치**: npm Automation 토큰 재발급 → `NPM_TOKEN` secret 갱신 → 워크플로 rerun. 미발행 버전이라 같은 태그 재사용 가능 | +| GGUF 가중치 미번들 | 라이선스·용량 문제로 설치파일에 못 넣음 | 운영자가 USB 반입. 권장 모델팩 결정 필요 | +| Qwen3 8B "권장" 판정 보류 | 개발 머신 실측 0.75 tok/s — 타깃 사양(16GB 노트북) 미실측 | 실기기 측정 후 문서의 "장비에 따라 선택" 문구 확정 | ## 다음 한 걸음 -**실기기에서 로컬 LLM 채팅 1턴.** 데스크톱의 핵심 판매 포인트인데 한 번도 실제로 돈 적이 없다. +**클린 체크아웃에서 `bun install` → `bun run server:build:subprocess` 가 통과하는지 확인.** +이 한 줄이 갈림길이다 — 통과하면 로컬 스토어 오염이라 `build-win.ps1` 만 고치면 되고, +실패하면 의존성 해석 자체의 결함이라 별도 조사가 필요하다. 데스크톱의 핵심 판매 포인트인 +로컬 LLM 채팅이 여기에 걸려 있고, 아직 한 번도 실제로 돈 적이 없다. ## 건드리면 안 되는 것 diff --git a/decisions/active/2026-08-19-subprocess-servers-must-be-copied.md b/decisions/active/2026-08-19-subprocess-servers-must-be-copied.md index 7986272..7315c60 100644 --- a/decisions/active/2026-08-19-subprocess-servers-must-be-copied.md +++ b/decisions/active/2026-08-19-subprocess-servers-must-be-copied.md @@ -57,7 +57,68 @@ Error: piServerPath not configured. Cannot spawn Pi subprocess. - 서브프로세스 서버를 단일 바이너리로 번들하게 되면 이 복사 단계가 불필요해진다 - electron-builder 가 0건 매치 glob 을 오류로 처리하게 되면 검증 위치를 옮길 수 있다 -## 남은 확인 +## ⚠️ 정정 (2026-08-20) — 이 결정은 아직 **효력이 없다** -**이 수정은 소스에만 반영됐다.** 사용자의 설치본은 수정 전 빌드라 여전히 결함이 있다 — -새 릴리스를 만들어 자동 업데이트로 배포해야 실제로 해소된다. +v2.4.1 을 릴리스하고 설치본을 실측한 결과, `dist/resources/` 에 `pi-agent-server` 와 +`session-mcp-server` 가 **여전히 없다**. `llama` 는 들어왔다(정적 `resources/` 를 통해). + +위 결정이 잘못된 게 아니라 **적용 지점이 틀렸다.** 자산 복사 스크립트가 두 개다: + +| 스크립트 | 무엇을 복사하나 | 누가 부르나 | +| ------------------------------------------------- | --------------------------------- | ------------------------------------------------------- | +| `scripts/electron-build-resources.ts` (수정된 것) | 정적 자산 **+ 서브프로세스 서버** | `electron:build` 체인 (package.json:70) | +| `apps/electron/scripts/copy-assets.ts` | 정적 자산 + sapstack 에셋만 | **`build-win.ps1:396`** — 설치파일을 만드는 유일한 경로 | + +`build-win.ps1` 은 `bun run electron:build` 를 통째로 부르지 않고 조각(esbuild main, +`electron:build:preload`, `vite build`, `copy-assets.ts`)을 직접 부른다. 그래서 수정된 +스크립트가 **Windows 설치파일 경로에서 한 번도 실행되지 않았다.** `copy-assets.ts` 396행 +주석의 "Single source of truth" 는 사실이 아니다. + +### 왜 아직 안 고쳤나 + +`build-win.ps1` 에 `server:build:subprocess` + `electron:build:resources` 를 추가하려 +했으나, **`pi-agent-server` 가 로컬에서 빌드되지 않는다**: + +``` +error: Could not resolve: "@aws-crypto/crc32" + at node_modules/.bun/@earendil-works+pi-ai@0.80.6+.../ + @smithy/node-http-handler/node_modules/@smithy/core/dist-cjs/submodules/event-streams/index.js:1 +``` + +- `@smithy/core@3.25.1` 이 `@aws-crypto/crc32: 5.2.0` 을 정식 dependency 로 선언한다 +- `apps/desktop/bun.lock` 에도 등재돼 있고 `apps/desktop/node_modules/@aws-crypto/crc32` 는 존재한다 +- 그런데 `apps/desktop/node_modules/@earendil-works/pi-ai` 는 **저장소 루트** 스토어 + (`sapstack/node_modules/.bun/`) 로 심링크돼 있고, 그 스토어에는 crc32 가 없다 +- `bun install --frozen-lockfile` 재실행으로도 복구되지 않았다 + +**추적 결과 — 루트 `node_modules` 를 두 패키지 매니저가 나눠 쓰고 있다.** + +- 루트 `package.json` 의 workspaces 는 `["packages/*", "mcp", "extension"]` 로, + **`apps/desktop` 을 포함하지 않는다**. `apps/desktop` 은 자기 `bun.lock` 과 자기 + workspaces 를 가진 독립 루트다 +- 그런데 `apps/desktop` 에서 `bun install` 을 돌리면 bun 이 위로 올라가 + 루트 `package.json` 의 workspaces 필드를 보고 **`sapstack/` 을 모노레포 루트로 오인**해 + 스토어를 거기에 만든다 +- 같은 `sapstack/node_modules` 를 ci.yml 이 `npm ci` (packages/runtime · mcp · extension) + 로 따로 관리한다. npm 의 prune 이 bun 이 놓은 것을 걷어내면서 서브트리가 잘린다 +- 실증: 해석 경로에 `@aws-crypto/crc32` 를 수동 배치하니 다음 결핍(`@aws-crypto/util`), + 그 다음(`tslib`)이 연쇄로 드러났다 — 버전 충돌이 아니라 **서브트리 전체 부재**다 + (확인 후 `node_modules` 는 원상 복구했다) + +검증되지 않은 빌드 단계를 릴리스 워크플로에 넣으면 방금 복구한 파이프라인이 다시 깨진다. +**클린 체크아웃에서 `bun install` 후 `bun run server:build:subprocess` 가 통과하는지 +먼저 확인**한 다음 `build-win.ps1` 을 고칠 것. + +CI 러너는 매번 클린 체크아웃이라 통과할 가능성이 높지만(같은 `sapstack/node_modules` 를 +npm 과 bun 이 순서대로 쓰기 때문에 CI 에서도 재현될 여지가 있다), 추측으로 워크플로를 +바꾸지 않는다. 개발 머신에서 확인하지 못한 이유는 디스크 여유가 8.2G 뿐이라 +클린 클론을 만들 수 없었기 때문이다. + +> 근본 수리라면 `apps/desktop` 이 루트를 모노레포 루트로 오인하지 않게 만드는 것이다 +> (루트 workspaces 에 명시적으로 넣거나, `apps/desktop` 에 경계를 세우거나). +> 이 결정 레코드의 범위를 넘으므로 별도 판단이 필요하다. + +### 사용자 영향 (현재) + +설치본 2.4.1 에서도 **로컬 모델 채팅은 여전히 `piServerPath not configured` 로 죽는다.** +v2.4.1 이 실제로 고친 것은 릴리스 파이프라인과 자동 업데이트 경로이지 이 결함이 아니다.