프로젝트 소개

dotfiles-web은 README에서 11개의 저장소와 3계층 터미널 환경(Core → OS-native → Role)으로 설명되는 dotgibson dotfiles 시스템의 공개 쇼케이스 및 문서 허브입니다. 이 사이트는 머신을 설정하는 것이 아니라 해당 시스템을 문서화하는 것이므로, 명시적으로 3계층 모델에 포함되지 않습니다. 사이트는 Astro로 구축되었으며, Tokyo Night 테마가 적용되어 GitHub Pages에 배포됩니다. 구조 README에는 다섯 가지 주요 경로가 나열되어 있습니다. 히어로 섹션, 3계층 모델, 저장소 맵 및 설치 안내가 포함된 랜딩 페이지, 플랫폼별 설치 가이드가 있는 시작하기 페이지, 계층 모델, subtree 근거, 로더 및 심층 분석을 다루는 아키텍처 페이지, 개념, 가이드, 참조 및 저장소별 생성 페이지가 있는 문서 허브, 그리고 각 저장소의 CHANGELOG.md를 반영하는 변경 로그 페이지입니다. 데이터 기반 콘텐츠 이 사이트는 데이터 기반이며 대부분 소스에서 파생됩니다. 쇼케이스 카드, 저장소별 문서 페이지, "by the numbers" 스트립 및 변경 로그는 src/data 하위 파일과 형제 저장소에서 가져오므로, 문서가 설명하는 코드와 서로 어긋나지 않습니다. 편집 가능한 입력 항목으로는 src/data/site.ts(사이트 이름, 소유자, 네비게이션, GitHub 링크), src/data/repos.ts(저장소 맵 및 저장소별 설명과 상태), src/data/install.ts(플랫폼별 설치 단계) 및 src/content/docs 하위의 Markdown 페이지가 있습니다. scripts/ 하위의 4개 수집기는 형제 저장소에서 생성 데이터를 도출합니다. collect-metrics.mjs는 11개의 dotfiles 저장소에서 generated.json을 생성하고, collect-snippets.mjs는 6개 저장소의 엄선된 8개 파일에서 snippets.json을 생성하며, collect-corpus.mjs는 htpx에서 corpus.json을, collect-coverage.mjs는 dotfiles-Defense에서 coverage.json을 생성합니다. 엄격함 및 출처 가드 npm run data는 게시 경로로 설명되며 매우 엄격합니다. 저장소가 누락되었거나, 형제 저장소가 기능 브랜치에 머물러 있거나, 수집기가 읽는 파일에 커밋되지 않은 수정 사항이 있는 경우 실행이 실패합니다. README에 따르면, 과거에 기능 브랜치로 체크아웃된 dotfiles-core가 Core의 main에 없는 변경 로그 항목을 게시했던 사례 때문에 이 확인 절차가 존재합니다. 개별 수집기와 npm run data:lenient는 탐색적 실행을 위해 관대하게 유지됩니다. README는 무해한 경우(소스 저장소 부재 — 커밋된 파일이 변경되지 않음, exit 0)와 오염된 데이터를 여전히 기록하는 경우(플릿이 존재하지만 깨끗하지 않음, generatedFrom.clean: false로 표시됨)를 구분합니다. 두 가지 가드가 이 출처 판정을 읽습니다. npm install 또는 npm run hooks:install로 설치되는 pre-commit 훅(한 대의 머신에서 generated.json 및 snippets.json을 처리)과 data-freshness.yml의 committed-data-provenance CI 작업(모든 PR 대상)입니다. 훅은 core.hooksPath가 설정된 경우 크게 건너뛰며 DOTFILES_ALLOW_DIRTY_DATA=1 또는 --no-verify로 우회할 수 있지만, CI 작업은 불가능합니다. 자동화 fleet-sync.yml은 매주 4개의 수집기를 모두 실행하고 출력값이 변경되면 PR을 생성합니다. data-freshness.yml은 커밋된 4개 파일 중 하나라도 소스와 일치하지 않거나, generated.json의 Core 버전이 최신 dotfiles-core 릴리스보다 낮을 때 CI를 실패 처리합니다. main으로 푸시하면 deploy.yml(Astro 빌드 → GitHub Pages)이 트리거되며, 소스 저장소는 docs/WEBHOOK-SETUP.md에 설명된 대로 수명이 짧은 GitHub App 토큰을 통해 인증된 repository_dispatch를 통해 재빌드를 요청할 수 있습니다. 개발 사전 요구 사항은 npm이 포함된 Node.js이며, 프로젝트는 표준 Astro 프로젝트입니다. 주요 명령어로 npm run dev(로컬 개발 서버), npm run build(dist/로 프로덕션 빌드), npm run preview 및 npm run check(Astro 타입 및 콘텐츠 컬렉션 확인)가 있습니다. 기여 가이드에서는 소스-오브-트루스(source-of-truth) 저장소를 정전(canonical)으로 취급하고, 콘텐츠를 페이지에 하드코딩하는 대신 데이터 파일에 유지하며, 푸시 전 npm run check와 npm run build를 통과할 것을 요청합니다. MIT 라이선스가 적용됩니다.