lumosframework/lumos-for-astro

Lumos 사이트 업그레이드

이 작업이 완료되면 두 가지 조건이 충족되어야 하며, 이 두 조건은 서로 상충됩니다:

1. 사용자가 작성한 내용이 손실되지 않음. 오버라이드, 페이지, 토큰, 컴포넌트 모두 보존.
2. 이전 규칙이 남아있지 않음. 이름이 변경된 속성은 변경되고, 이동된 컴포넌트는 이동되며, 폐기된 패턴은 제거됨.

사용자의 작업을 그대로 두면 두 번째 조건이 실패합니다. 덮어써버리면 첫 번째 조건이 실패합니다. 해결책은 3-way 병합 — 사용자가 시작했던 지점, 현재의 지점, 오늘 배포되는 지점 — 이 세 지점이 일치하지 않을 때는 추측하지 않고 질문하는 엄격함이 필요합니다.

사이트가 시작된 지점

업그레이드는 시작 지점에 대한 정확한 정보가 있어야만 제대로 작동합니다.

node -p "JSON.parse(require('fs').readFileSync('package.json')).lumos ?? 'unstamped'"

• 스탬프 있음 — create-lumos가 기록한 { version, commit, scaffolded }. version은 사이트가 만들어진 릴리스(참고용), commit은 병합 기준점으로 사용되며, 이 commit이 중요합니다. version과 commit은 중복되지 않습니다: 릴리스 사이에 스캐폴딩된 사이트는 해당 버전과 이후에 추가된 내용을 포함하므로, commit만이 정확한 정도를 알려줍니다. version이 추가되기 전에 스탬프된 사이트는 commit만 가지고 있으며, 이로도 충분합니다. 해당 commit이 병합 기준(merge base)입니다. 이를 가져오면 프레임워크의 코드 라인과 사용자의 코드 라인을 정확히 알 수 있습니다.
• 스탬프 없음 — 스탬핑 이전의 사이트입니다. v0.0.1을 기준으로 간주합니다. 보고서에 명확히 밝혀야 합니다: 기준은 추정치이므로 병합 시 충돌이 더 많이 발생할 수 있고, 더 많은 검토가 필요합니다.

사이트 자체의 package.json 버전은 아무 의미가 없습니다 — create-lumos는 모든 새 사이트를 0.0.1로 설정합니다. 이것을 프레임워크 버전으로 해석하지 마십시오.

단계

1. 현재 상태를 커밋

작업 트리가 더티(dirty)인 상태에서는 시작하지 마십시오 — 업그레이드 도중의 diff는 이전 작업과 섞이면 읽을 수 없습니다.

git status --porcelain          # 반드시 비어 있어야 함
git commit --allow-empty -m "Before Lumos upgrade"

빈 커밋은 의도적입니다: 전체 업그레이드를 검토할 기준점이 되며, git diff <해당 커밋> 리뷰가 가능해집니다.

2. 사이트를 사진 촬영

아무것도 변경되기 전에, 개발 서버를 실행한 상태에서:

astro dev --background
node .agents/skills/lumos-upgrade-version/visual-check.mjs capture before

데스크탑과 모바일에서 모든 정적 경로를 촬영합니다. 이는 8단계에서 비교할 증거이며, 이후에는 촬영할 수 없습니다.

3. 두 레퍼런스 복사본 가져오기

npm create lumos@latest .lumos-upgrade/latest    # 현재 배포 버전

그리고 병합 기준 — 사이트가 스캐폴딩된 커밋:

curl -sL https://codeload.github.com/lumosframework/lumos-for-astro/tar.gz/<commit> \
  | tar -xz -C .lumos-upgrade --one-top-level=base --strip-components=1

이제 세 개의 트리가 존재합니다: base (시작 지점), 사이트 (현재 지점), latest (도달할 지점).

4. 모든 파일을 네 가지 유형으로 분류

프레임워크의 표면에 해당하는 각 파일(컴포넌트, 레이아웃, 스타일, 유틸리티)에 대해:

base vs site	base vs latest	의미	처리 방법
same	same	양쪽에서 수정되지 않음	그대로 둠
same	changed	프레임워크 변경, 사용자 수정 없음	최신 버전으로 전체 교체
changed	same	사용자 오버라이드, 프레임워크 변경 없음	사용자 버전 유지
changed	changed	양쪽 모두 변경됨	3-way 병합, 충돌은 보고서에 기록

src/pages, src/content, src/assets는 정의상 사용자의 것입니다 — 절대 교체하지 마십시오. 하지만 6단계에서 마이그레이션이 필요합니다.

.agents/skills는 한 가지 예외를 제외하고 전체 교체합니다. 스킬의 본문은 프레임워크의 것이며 최신 버전으로 이동해야 하지만, 스킬이 프로젝트에서 작성한 섹션을 포함할 수 있습니다 — /lumos-import-webflow의 This project가 그 예이며, 다른 곳에는 없는 경로, 공급자, CMS 필터를 기록합니다. 새 파일을 가져오기 전에 해당 섹션을 그대로 보존하고 보고서에 그렇게 했다고 명시하십시오. 전체 교체 시 다른 출처가 없는 레코드가 손실됩니다.

5. base.css를 교체하지 않고 병합

전역 CSS는 네 번째 유형(양쪽 변경)에 속할 가능성이 가장 높습니다: 프레임워크는 토큰을 추가하고, 사용자는 브랜드 색상과 폰트를 변경합니다. 토큰별로 3-way 병합하고, 두 가지 규칙을 따르십시오:

• 사용자가 변경한 토큰은 사용자의 값을 유지합니다. 프레임워크가 기본값을 변경했더라도 마찬가지입니다. 사용자의 브랜드 색상은 낡은 기본값이 아닙니다.
• 프레임워크가 추가한 토큰은 프레임워크의 값으로, 끝에 덧붙이지 않고 자체 섹션에 배치합니다.

양쪽 모두 변경된 모든 토큰은 두 값을 모두 보고서에 기재하십시오. 대신 선택하지 마십시오.

6. 사이트 자체 코드 마이그레이션

base와 latest를 비교하여 변경된 사항을 파악한 후, src/pages와 사용자가 작성한 모든 것에 적용합니다:

• 이름이 변경되거나 이동된 컴포넌트 — 모든 import와 태그를 업데이트합니다. 폴더가 이동되고 접두사가 사라진 컴포넌트(FormInput → Form/Input.astro)는 두 가지 변경을 한 번에 처리해야 합니다.
• 이름이 변경된 속성 — 모든 호출 지점에서 이름을 변경합니다.
• 제거된 속성 — 멈추고 질문하십시오. 각 속성에 대해 세 가지 실제 옵션을 제시하십시오: 로컬 오버라이드로 속성 유지, 제거, 또는 대체 기능으로 이동. 절대 조용히 결정하지 마십시오; 제거된 속성은 보통 의미가 있었습니다.
• 삭제된 컴포넌트 — 사용자의 복사본을 유지하십시오. base에서 컴포넌트를 사이트의 자체 컴포넌트 폴더로 복사하여 사이트가 계속 빌드되고 동일하게 보이도록 하고, 플래그를 표시하십시오: 이 컴포넌트는 더 이상 프레임워크에서 유지보수되지 않으며, 대체 컴포넌트가 있다면 함께 알립니다.

7. 빌드 확인

npx astro check && npx astro build

스크린샷에 접근하기 전에 두 단계가 모두 깨끗해야 합니다. 지금 발견된 타입 오류는 놓친 마이그레이션입니다.

이 기회에 Astro 페어링도 확인하십시오. Astro는 프레임워크가 아닌 사이트 자체의 의존성입니다 — Lumos는 스캐폴딩될 뿐 설치되지 않습니다 — 따라서 업그레이드는 확인할 자연스러운 시점이지, 강제할 핑계가 아닙니다. 사이트의 astro 버전을 병합 중인 릴리스와 비교하십시오; 사이트가 메이저 버전에서 뒤쳐져 있다면 보고서에 명시하고 소유자가 결정하도록 하십시오.

수동으로 버전을 올리지 말고 npx @astrojs/upgrade를 사용하십시오. Astro와 함께 @astrojs/* 통합을 이동하며, @astrojs/sitemap은 astro에 대한 피어 의존성을 선언하지 않습니다 — 따라서 짝이 맞지 않으면 경고 없이 설치되어 빌드 실패나 사이트맵이 조용히 생성되지 않는 문제로 나타납니다.

8. 변경되지 않았음을 증명

node .agents/skills/lumos-upgrade-version/visual-check.mjs capture after
node .agents/skills/lumos-upgrade-version/visual-check.mjs compare

2단계의 각 경로에 대해 안티앨리어싱 허용치를 적용하여 픽셀 단위로 비교하고, 픽셀의 0.1% 이상 차이가 나는 경우 강조된 diff를 생성합니다. 무언가 이동되었을 때 종료 코드가 0이 아닙니다.

디자인을 변경하는 업그레이드는 어딘가 잘못된 것입니다 — 토큰이 잘못 병합되었거나, 속성이 누락되었거나, 동일하지 않은 컴포넌트로 교체되었을 수 있습니다. diff 이미지에서 역추적하여 각각이 설명될 때까지 작업하십시오. 일부는 정당합니다: 업스트림의 실제 버그 수정은 픽셀을 이동시킬 수 있습니다. 규칙은 **"차이가 없음"이 아니라 "설명되지 않은 차이가 없음"**입니다.

9. 결과 커밋

git add -A && git commit -m "Upgrade Lumos to <commit>"

package.json의 스탬프를 방금 병합한 커밋으로 업데이트하여 다음 업그레이드가 정확한 기준점을 가질 수 있도록 합니다. 그런 다음 .lumos-upgrade/를 삭제합니다.

보고서

• 최신 버전에서 가져옴 — 수정되지 않아 전체 교체된 파일
• 사용자 것으로 유지 — 보존된 오버라이드, 프레임워크 변경 거부됨
• 병합됨 — 양쪽이 변경된 파일, 출처별 내용 기재
• 마이그레이션됨 — 사용자 코드에 적용된 이름 변경 및 이동, 개수 표시
• 유지됨(alive) — 업스트림에서 삭제되었으나 사이트에 복사된 컴포넌트, 대체 컴포넌트 정보 포함
• 응답됨 — 제거된 속성과 각 속성에 대한 사용자의 선택
• 시각적 차이 — 이동된 모든 뷰와 그 이유
• 미해결 - 해결되지 않은 모든 사항. 이 목록이 비어 있지 않더라도 명시되어 있으면 업그레이드는 완료될 수 있습니다.

버전

• 스킬 버전 — 1.0.0.
• 프레임워크 — 아직 공식 릴리스는 없습니다: create-lumos는 main 브랜치의 HEAD에서 스캐폴딩하므로, "최신"은 가장 최신 커밋을 의미하며, 병합 기준은 태그 대신 커밋입니다. 태그된 릴리스가 도착하면 스탬프에서 태그를 우선 사용하고, 4단계에서 맹목적으로 diff하는 대신 변경 로그를 읽으십시오.

Claude Code 없이 사용하기

단계는 일반 git과 node입니다. visual-check.mjs는 headless Chrome과 sharp가 필요하며, Mac의 Astro 프로젝트에는 이미 모두 있습니다. 자동 트리거 및 /lumos-upgrade만 Claude Code 기능입니다.